dicer

README

Dicer

Run virtual machines from container images, on one host.

Dicer pulls an OCI image, converts it to a read-only root filesystem and boots it as a VM under Cloud Hypervisor or Firecracker, with a writable overlay on top.

Requirements

• Linux with KVM (/dev/kvm)
• erofs-utils (mkfs.erofs) and e2fsprogs (mke2fs)
• IPv4 forwarding enabled

Install

curl -fsSL https://raw.githubusercontent.com/konradasb/dicer/main/scripts/install.sh | bash

This builds dicer and dicerd from source and installs dicerd as a systemd service.

Quickstart

Create a network and import Dicer's kernel (on arm64, use --arch aarch64, Image-arm64 and its checksum from the release's SHA256SUMS):

$ dicer network create default --subnet 172.20.0.0/16
$ dicer kernel import linux-6.18 --arch x86_64 \
    --url https://github.com/konradasb/dicer-kernel/releases/download/v6.18.53-1/vmlinux-x86_64 \
    --sha256 ca5db6c291deb8a409db1f1ab14cc55ef6d35504daf17fc0f5577ffc1662b669

With one network and one kernel, instances use them by default:

$ dicer run -d --name web -p 8080:80 nginx:1.27
$ dicer ps
$ dicer exec web sh
$ dicer logs -f web
$ dicer stop web
$ dicer rm web

See dicer --help for every command.

Configuration

dicerd reads /etc/dicerd/config.yaml. The file is optional: every key has a default, and unknown keys are rejected. The configuration reference shows every key with its default, and dicerd validate checks a file before the daemon uses it.

License

MIT. See LICENSE.

Documentation

Overview

Package dicer connects Go programs to a Dicer daemon.

The API itself is the gRPC service in proto/dicerd/v1, and its generated code is what every client uses, whatever its language. This package only makes the connection: to the local daemon's socket by default, or to a daemon's TCP listener, with TLS.

c, err := dicer.NewClient()
if err != nil {
	return err
}
defer c.Close()

inst, err := c.GetInstance(ctx, &dicerdv1.GetInstanceRequest{Name: "web"})

A daemon on another machine is named by its address, a gRPC target:

c, err := dicer.NewClient(dicer.WithAddress("host:7443"), dicer.WithTLS(cfg))

The socket is protected by its file permissions. A TCP listener is unauthenticated unless the daemon is configured with TLS.

Errors are gRPC statuses, whose codes the service's documentation gives:

if status.Code(err) == codes.NotFound {
	...
}

Index

• Constants
• type Client
  • func NewClient(opts ...Option) (*Client, error)
  • func (c *Client) Close() error
• type Option
  • func WithAddress(target string) Option
  • func WithDialOptions(opts ...grpc.DialOption) Option
  • func WithKeepalive(interval, timeout time.Duration) Option
  • func WithTLS(cfg *tls.Config) Option

Constants

const (
	// DefaultKeepaliveInterval is how long a connection may carry nothing
	// before the client pings the daemon.
	DefaultKeepaliveInterval = 30 * time.Second

	// DefaultKeepaliveTimeout is how long the client waits for the answer
	// to a ping before giving the connection up.
	DefaultKeepaliveTimeout = 10 * time.Second
)

The keepalive a client uses unless WithKeepalive says otherwise.

const DefaultAddress = "unix://" + defaults.Socket

DefaultAddress is where a daemon serves its API unless configured otherwise: its Unix socket, as a gRPC target.

Types

type Client

type Client struct {
	dicerdv1.DaemonServiceClient
	// contains filtered or unexported fields
}

Client is a connection to a Dicer daemon. It is the generated dicerdv1.DaemonServiceClient, so its methods are the API's RPCs, taking and returning the messages in package dicerdv1, and its errors are gRPC statuses.

A Client is safe for concurrent use and should be closed when done.

func NewClient

func NewClient(opts ...Option) (*Client, error)

NewClient connects to a daemon, by default the local one:

c, err := dicer.NewClient()

A daemon's TCP listener, over TLS:

c, err := dicer.NewClient(dicer.WithAddress("host:7443"), dicer.WithTLS(cfg))

Connecting is lazy: an unreachable daemon is reported by the first call. A local socket that is not there is reported here.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the daemon. Calls in flight are cancelled.

type Option

type Option func(*options)

An Option configures a Client.

func WithAddress

func WithAddress(target string) Option

WithAddress sets the daemon's address, as a gRPC target: "unix:///path/to/socket", or "host:port" for its TCP listener. The default is DefaultAddress.

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) Option

WithDialOptions adds gRPC dial options, such as interceptors. They are applied after WithKeepalive's, so a keepalive given here replaces it.

func WithKeepalive

func WithKeepalive(interval, timeout time.Duration) Option

WithKeepalive sets how long a connection may carry nothing before the client pings the daemon, and how long it waits for the answer before giving the connection up, failing the calls in flight on it with codes.Unavailable. That is how a daemon that has gone without closing the connection, because its host lost power or the network between dropped, is noticed; without it, a call waits for as long as its context lets it.

The defaults are DefaultKeepaliveInterval and DefaultKeepaliveTimeout. An interval of zero turns the pings off, and a timeout of zero is the default. gRPC raises an interval below 10s to 10s, and a daemon closes the connection of a client that pings more often than its api.keepalive.min_client_interval.

A connection over a Unix socket is never pinged: the kernel closes it if the daemon goes.

func WithTLS

func WithTLS(cfg *tls.Config) Option

WithTLS secures the connection with cfg. A daemon's TCP listener needs it unless it is served without TLS; its certificate is checked against the address's host unless cfg names another.