Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CLOUDABI-RUN(1)		FreeBSD	General	Commands Manual	       CLOUDABI-RUN(1)

NAME
     cloudabi-run -- execute CloudABI processes

SYNOPSIS
     cloudabi-run [-e] path

DESCRIPTION
     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 descrip-
     tor.  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 <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_map_iterate(), and
     argdata_seq_iterate().  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	Cloud-
     ABI process can obtain the	file descriptor	numbers	of these objects by
     calling argdata_get_fd().

     CloudABI executables can be executed directly on operating	systems	that
     have a compatibility layer	for CloudABI executables.  Alternatively,
     cloudabi-run includes a built-in emulator that can	be enabled by provid-
     ing the -e	flag.  The use of this emulator	is strongly discouraged	if the
     operating system provides native support for CloudABI.

YAML TAGS
     The following YAML	tags can be used to provide resources to CloudABI pro-
     cesses:

     tag:nuxi.nl,2015:cloudabi/fd: int
	   Exposes a file descriptor by	decimal	file descriptor	number,	or the
	   special values ``stdout'' and ``stderr''.

     tag:nuxi.nl,2015:cloudabi/file: map
	   Opens a file	for reading.  File objects have	the following
	   attributes:

	   path: str
		 The path of the file.

     tag:nuxi.nl,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''.

EXAMPLES
     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 <stdio.h>
	   #include <stdlib.h>

	   void	program_main(const argdata_t *ad) {
	     argdata_seq_iterator_t it;
	     argdata_seq_iterate(ad, &it);
	     const argdata_t *value;
	     while (argdata_seq_get(&it, &value)) {
	       int fd;
	       if (argdata_get_fd(value, &fd) == 0)
		 dprintf(fd, "Hello, world\n");
	       argdata_seq_next(&it);
	     }
	     exit(0);
	   }
	   $ cat hello.yaml
	   %TAG	! tag:nuxi.nl,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"
				    "Content-Length: 13\r\n\r\n"
				    "Hello, world\n";
		 write(connfd, buf, sizeof(buf)	- 1);
		 close(connfd);
	       }
	     }
	     exit(1);
	   }
	   $ cat webserver.yaml
	   %TAG	! tag:nuxi.nl,2015:cloudabi/
	   ---
	   !socket
	     bind: '[::]:12345'
	   $ x86_64-unknown-cloudabi-cc	-o webserver webserver.c
	   $ cloudabi-run webserver < webserver.yaml

IMPLEMENTATION NOTES
     cloudabi-run invokes a helper utility called cloudabi-reexec before exe-
     cuting the	executable stored at path.  cloudabi-reexec is a CloudABI exe-
     cutable 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 con-
     tiguous, starting at file descriptor zero.

     The emulator makes	no attempt to sandbox the execution of running pro-
     cesses.  It should	therefore only be used for development and testing
     purposes.	Using it in production is strongly discouraged.

AUTHORS
     CloudABI has been developed by Nuxi, the Netherlands: https://nuxi.nl/.

FreeBSD	Ports 11.2		August 2, 2016		    FreeBSD Ports 11.2

NAME | SYNOPSIS | DESCRIPTION | YAML TAGS | EXAMPLES | IMPLEMENTATION NOTES | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cloudabi-run&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help