Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  CLOUDABI-RUN (1)


cloudabi-run - execute CloudABI processes


Yaml Tags
Implementation Notes


cloudabi-run path


CloudABI is a purely capability-based runtime environment, meaning that access to system resources is solely based on the set of file descriptor that the process possesses. For example, CloudABI processes can only access a file if it possesses a file descriptor for that file or one of its parent directories. This makes it critical that a CloudABI process is provided the right set of file descriptors on startup.

The problem with providing a set of file descriptors on startup is that the file descriptors either need to be placed at fixed indices or that a separate configuration file describes the purpose of each file descriptor. The latter is hard to accomplish, due to the fact that CloudABI programs cannot open configuration files from arbitrary locations on the filesystem.

To simplify program configuration and at the same time make it easier to safely set up the initial set of file descriptors, CloudABI processes can be launched using the cloudabi-run utility. cloudabi-run executes a CloudABI program stored at a path and provides it a copy of YAML data read from standard input. The YAML data is provided in an already parsed form and can be accessed by using the alternative entry point program_main:

#include <program.h>

void program_main(const argdata_t *ad);

The YAML data can be traversed by using the
.In argdata.h functions argdata_get_binary, argdata_get_bool, argdata_get_float, argdata_get_int, argdata_get_str, argdata_get_str_c, argdata_get_timestamp, argdata_iterate_map, and argdata_iterate_seq. The names of these functions correspond to the respective YAML types.

By default, cloudabi-run executes the process with an empty set of file descriptors. File descriptors can be granted to the process by attaching them to the YAML data as objects using specialized YAML tags. The CloudABI process can obtain the file descriptor numbers of these objects by calling argdata_get_fd.


The following YAML tags can be used to provide resources to CloudABI processes:,2015:cloudabi/fd: int
  Exposes a file descriptor by decimal file descriptor number, or the special values "stdout" and "stderr".,2015:cloudabi/file: map
  Opens a file for reading. File objects have the following attributes:
path: str
  The path of the file.,2015:cloudabi/socket: map
  Creates a socket and binds it to a specified address. Socket objects have the following attributes:
bind: str
  The address to which the socket should be bound. If the address starts with a /, this creates a UNIX domain socket and binds it to the path provided. Otherwise, it resolves the address using getaddrinfo(3).
type: str
  Socket type. Valid types are "dgram" for datagram sockets, "seqpacket" for sequenced-packet sockets , and "stream" for stream sockets. The default value is "stream".


The following example shows a program that writes a fixed message to all of the file descriptors stored in a sequence. With the configuration provided, it writes the message to standard output three times in a row.
$ cat hello.c
#include <argdata.h>
#include <program.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>

static bool print_message(const argdata_t *ad, void *unused) { int fd; if (argdata_get_fd(ad, &fd) == 0) dprintf(fd, "Hello, world\n"); return true; }

void program_main(const argdata_t *ad) { argdata_iterate_seq(ad, print_message, NULL); exit(0); } $ cat hello.yaml %TAG !,2015:cloudabi/ --- - !fd stdout - !fd stdout - !fd stdout $ x86_64-unknown-cloudabi-cc -o hello hello.c $ cloudabi-run hello < hello.yaml Hello, world Hello, world Hello, world

Below is a simple web server that writes simple responses to incoming requests. With the configuration provided, it listens on TCP port 12345.

$ cat webserver.c
#include <sys/socket.h>

#include <argdata.h> #include <program.h> #include <stdlib.h> #include <unistd.h>

void program_main(const argdata_t *ad) { int sockfd; if (argdata_get_fd(ad, &sockfd) == 0) { int connfd; while ((connfd = accept(sockfd, NULL, NULL)) >= 0) { const char buf[] = "HTTP/1.1 200 OK\r\n" "Content-Type: text/plain\r\n\r\n" "Hello, world\n"; write(connfd, buf, sizeof(buf) - 1); close(connfd); } } exit(1); } $ cat webserver.yaml %TAG !,2015:cloudabi/ --- !socket bind: $ x86_64-unknown-cloudabi-cc -o webserver webserver.c $ cloudabi-run webserver < webserver.yaml


cloudabi-run invokes a helper utility called cloudabi-reexec before executing the executable stored at path. cloudabi-reexec is a CloudABI executable that merely acts as a proxy to guarantee that the process already runs in capabilities mode before executing the requested binary, making it safe to run cloudabi-run on third-party executables.

As CloudABI’s program_exec function scans the argument data to obtain a list of file descriptors that need to be retained in the new process, cloudabi-run guarantees that any file descriptors that are not specified in the YAML data are closed. File descriptors are renumbered to be contiguous, starting at file descriptor zero.


CloudABI has been developed by Nuxi, the Netherlands:
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.