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

FreeBSD Manual Pages

  
 
  

home | help
CLOUDABI-RUN(1)		  BSD 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 ac-
     cess 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 at-
	   tributes:

	   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 ob-
	   jects have the following attributes:

	   bind: str
		 The address to	which the socket should	be bound.  If the ad-
		 dress 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 re-
     quests.  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/.

BSD				August 2, 2016				   BSD

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