dicer

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2026 License: MIT Imports: 11 Imported by: 0

README

Dicer

OpenSSF Scorecard test lint security Go Reference

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

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

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

Variables

This section is empty.

Functions

This section is empty.

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 or keepalives.

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
dicer command
Command dicer is the command-line client for dicerd.
 Command dicer is the command-line client for dicerd.
dicer-agent command
Command dicer-agent serves exec requests inside a Dicer guest.
 Command dicer-agent serves exec requests inside a Dicer guest.
dicer-init command
Command dicer-init runs as PID 1 inside a Dicer guest.
 Command dicer-init runs as PID 1 inside a Dicer guest.
dicerd command
Command dicerd is the Dicer host daemon.
 Command dicerd is the Dicer host daemon.
internal
archive
Package archive packs one file or directory as a tar stream and unpacks it with cp's placement rules:
 Package archive packs one file or directory as a tar stream and unpacks it with cp's placement rules:
atomicfile
Package atomicfile writes files so that a crash cannot leave a partial one in place of a good one.
 Package atomicfile writes files so that a crash cannot leave a partial one in place of a good one.
cli
Package cli implements the dicer command-line client.
 Package cli implements the dicer command-line client.
cli/printer
Package printer renders a Printable as a table, JSON, YAML or a Go template.
 Package printer renders a Printable as a table, JSON, YAML or a Go template.
cli/remote
Package remote is the daemons the CLI knows, kept with the current one in ~/.config/dicer/remotes.yaml, and how each is reached.
 Package remote is the daemons the CLI knows, kept with the current one in ~/.config/dicer/remotes.yaml, and how each is reached.
compose
Package compose reads compose files: a project's instances, networks and volumes, described together in YAML as Docker Compose describes containers, and turned into the requests the daemon's API takes.
 Package compose reads compose files: a project's instances, networks and volumes, described together in YAML as Docker Compose describes containers, and turned into the requests the daemon's API takes.
daemon
Package daemon assembles and runs dicerd: it loads the configuration, wires the services together and manages the process lifecycle.
 Package daemon assembles and runs dicerd: it loads the configuration, wires the services together and manages the process lifecycle.
defaults
Package defaults is where Dicer lives on a host unless configured otherwise: the locations more than one of its packages or programs must agree on, such as the socket the daemon serves on and a client looks at.
 Package defaults is where Dicer lives on a host unless configured otherwise: the locations more than one of its packages or programs must agree on, such as the socket the daemon serves on and a client looks at.
errdefs
Package errdefs defines the classes of error the daemon's code returns, matched with errors.Is.
 Package errdefs defines the classes of error the daemon's code returns, matched with errors.Is.
events
Package events keeps the log of types.Events recorded on this host and delivers new ones to subscribers.
 Package events keeps the log of types.Events recorded on this host and delivers new ones to subscribers.
filestore
Package filestore stores the instance, network, volume and kernel definitions as YAML files, cached in memory and written through:
 Package filestore stores the instance, network, volume and kernel definitions as YAML files, cached in memory and written through:
grpcapi
Package grpcapi implements the DaemonService gRPC service and the audit interceptors in front of it.
 Package grpcapi implements the DaemonService gRPC service and the audit interceptors in front of it.
guest
Package guest defines the contract between the host and a guest: the Config written to the config disk, the Status read from the status disk, and the agent's port.
 Package guest defines the contract between the host and a guest: the Config written to the config disk, the Status read from the status disk, and the agent's port.
guest/agent
Package agent runs inside the guest and serves the host's exec, copy, probe and shutdown requests over vsock.
 Package agent runs inside the guest and serves the host's exec, copy, probe and shutdown requests over vsock.
guest/boot
Package boot is the guest's PID 1.
 Package boot is the guest's PID 1.
hostinfo
Package hostinfo reports the physical resources of the machine the daemon runs on, read from /proc.
 Package hostinfo reports the physical resources of the machine the daemon runs on, read from /proc.
hostnet
Package hostnet configures the host networking a VM needs: bridges, TAP devices, iptables NAT rules and traffic shaping.
 Package hostnet configures the host networking a VM needs: bridges, TAP devices, iptables NAT rules and traffic shaping.
hypervisor
Package hypervisor defines the VM specification and the operations a virtual machine monitor must support.
 Package hypervisor defines the VM specification and the operations a virtual machine monitor must support.
hypervisor/cloudhypervisor
Package cloudhypervisor provides primitives to interact with the openapi HTTP API.
 Package cloudhypervisor provides primitives to interact with the openapi HTTP API.
hypervisor/firecracker
Package firecracker implements the hypervisor interfaces with Firecracker.
 Package firecracker implements the hypervisor interfaces with Firecracker.
image
Package image pulls container images and converts them into read-only EROFS disks a guest boots from.
 Package image pulls container images and converts them into read-only EROFS disks a guest boots from.
image/reference
Package reference parses OCI image references and resolves tags to digests.
 Package reference parses OCI image references and resolves tags to digests.
initrd
Package initrd builds the initramfs a guest boots from, carrying dicer-init and dicer-agent.
 Package initrd builds the initramfs a guest boots from, carrying dicer-init and dicer-agent.
kernel
Package kernel downloads and caches guest kernels, verifying their SHA-256 when given.
 Package kernel downloads and caches guest kernels, verifying their SHA-256 when given.
metrics
Package metrics exports dicerd's Prometheus metrics.
 Package metrics exports dicerd's Prometheus metrics.
naming
Package naming is the rule every name Dicer gives a resource follows: an instance's, a network's, a snapshot's, a remote's.
 Package naming is the rule every name Dicer gives a resource follows: an instance's, a network's, a snapshot's, a remote's.
network
Package network assigns guest addresses on host-local networks and names their interfaces.
 Package network assigns guest addresses on host-local networks and names their interfaces.
process
Package process provides handles on long-lived processes such as VMMs, started or adopted, that report when the process exits.
 Package process provides handles on long-lived processes such as VMMs, started or adopted, that report when the process exits.
registry
Package registry talks to OCI registries: resolving references, pulling manifests and layers, and exporting an unpacked root filesystem.
 Package registry talks to OCI registries: resolving references, pulling manifests and layers, and exporting an unpacked root filesystem.
types
Package types is the daemon's model of what it manages: instances, images, networks, volumes, kernels, snapshots and the events about them.
 Package types is the daemon's model of what it manages: instances, images, networks, volumes, kernels, snapshots and the events about them.
version
Package version is the identity of the binary it is linked into, set at link time with -X.
 Package version is the identity of the binary it is linked into, set at link time with -X.
vm
Package vm implements the virtual machine lifecycle: starting, stopping, pausing and deleting instances.
 Package vm implements the virtual machine lifecycle: starting, stopping, pausing and deleting instances.
volume
Package volume provisions the persistent disks instances mount: sparse files with a filesystem, independent of any instance.
 Package volume provisions the persistent disks instances mount: sparse files with a filesystem, independent of any instance.
proto
diceragent/v1
dicerd/v1
tools
docgen command
Command docgen writes the documentation site's command line reference, generated from the commands themselves.
 Command docgen writes the documentation site's command line reference, generated from the commands themselves.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.