Haconiwa

Ruby on Container / helper tools with DSL for your handmade linux containers

Installation

This gem only works on Linux systems, as using cgroup, Linux namespace and Linux capabilities.

Some packages/dylibs/tools are used internally, so please install below before gem setup:

• libcap (libcap.so.2 is used via FFI)
• nsenter (e.g. yum install util-linux or such one)

Then, install it yourself globally(recommended using rbenv) as:

$ gem install haconiwa
$ rbenv rehash # if needed

Or add the line to your application's Gemfile:

gem 'haconiwa'

And then execute bundle.

Usage

Create the file example001.haco:

Haconiwa::Base.define do |config|
  config.name = "new-haconiwa001" # to be hostname

  config.cgroup["cpu.shares"] = 2048
  config.cgroup["memory.limit_in_bytes"] = "256M"
  config.cgroup["pid.max"] = 1024

  config.add_mount_point "/var/another/root/etc", to: "/var/your_rootfs/etc", readonly: true
  config.add_mount_point "/var/another/root/home", to: "/var/your_rootfs/home"
  config.mount_independent_procfs
  config.chroot_to "/var/your_rootfs"

  config.namespace.unshare "ipc"
  config.namespace.unshare "uts"
  config.namespace.unshare "mount"
  config.namespace.unshare "pid"

  config.capabilities.allow :all
  config.capabilities.drop "CAP_SYS_TIME"
end

Then use haconiwa binary installed with thie gem.

$ haconiwa run example001.haco

When you want to attach existing container:

$ haconiwa attach example001.haco

Note: attach subcommand allows to set PID(--target) or container name(--name) for dynamic configuration. And attach is not concerned with capabilities which is granted to container. So you can drop or allow specific caps with --drop/--allow.

DSL spec

• config.cgroup - Assign cgroup parameters via []=
• config.namespace.unshare - Unshare the namespaces like "mount", "ipc" or "pid"
• config.capabilities.allow - Allow capabilities on container root. Setting parameters other than :all should make this acts as whitelist
• config.capabilities.drop - Drop capabilities of container root. Default to act as blacklist
• config.add_mount_point - Add the mount point odf container
• config.mount_independent_procfs - Mount the independent /proc directory in the container. Useful if "pid" is unshared
• config.chroot_to - The new chroot root

You can pick your own parameters for your use case of container. e.g. just using mount namespace unshared, container with common filesystem, limit the cgroups for big resource job and so on.

Please look into example directory.

Library use case

require 'haconiwa'
base = Haconiwa::Base.define do |config|
  config.name = "new-haconiwa001" # to be hostname
  ...
end

# Run the container
base.run("/bin/bash")

# Or attach existing one
base.attach("/bin/bash")

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/udzura/haconiwa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

TODOs

• netns attachment
• more utilities such as ps
• better daemon handling

License

This gem is created under GNU General Public License Version 3.