Crate cloudabi

Expand description

PLEASE NOTE: This entire crate including this documentation is automatically generated from cloudabi.txt

§Nuxi CloudABI

CloudABI is what you get if you take POSIX, add capability-based security, and remove everything that’s incompatible with that. The result is a minimal ABI consisting of only 49 syscalls.

CloudABI doesn’t have its own kernel, but instead is implemented in existing kernels: FreeBSD has CloudABI support for x86-64 and arm64, and a patch-set for NetBSD and a patch-set for Linux are available as well. This means that CloudABI binaries can be executed on different operating systems, without any modification.

§Capability-Based Security

Capability-based security means that processes can only perform actions that have no global impact. Processes cannot open files by their absolute path, cannot open network connections, and cannot observe global system state such as the process table.

The capabilities of a process are fully determined by its set of open file descriptors (fds). For example, files can only be opened if the process already has a file descriptor to a directory the file is in.

Unlike in POSIX, where processes are normally started with file descriptors 0, 1, and 2 reserved for standard input, output, and error, CloudABI does not reserve any file descriptor numbers for specific purposes.

In CloudABI, a process depends on its parent process to launch it with the right set of resources, since the process will not be able to open any new resources. For example, a simple static web server would need to be started with a file descriptor to a TCP listener, and a file descriptor to the directory for which to serve files. The web server will then be unable to do anything other than reading files in that directory, and process incoming network connections.

So, unknown CloudABI binaries can safely be executed without the need for containers, virtual machines, or other sandboxing technologies.

Watch Ed Schouten’s Talk at 32C3 for more information about what capability-based security for UNIX means.

§Cloudlibc

Cloudlibc is an implementation of the C standard library, without all CloudABI-incompatible functions. For example, Cloudlibc does not have printf, but does have fprintf. It does not have open, but does have openat.

§CloudABI-Ports

CloudABI-Ports is a collection of ports of commonly used libraries and applications to CloudABI. It contains software such as zlib, libpng, boost, memcached, and much more. The software is patched to not depend on any global state, such as files in /etc or /dev, using open(), etc.

§Using CloudABI

Instructions for using CloudABI (including kernel modules/patches, toolchain, and ports) are available for several operating systems:

§Specification of the ABI

The entire ABI is specified in a file called cloudabi.txt, from which all headers and documentation (including the one you’re reading now) is generated.

Structs§

auxv: Auxiliary vector entry.
ciovec: A region of memory for scatter/gather writes.
condvar: A userspace condition variable.
device: Identifier for a device containing a file system. Can be used in combination with inode to uniquely identify a file on the local system.
dircookie: A reference to the offset of a directory entry.
dirent: A directory entry.
event: An event that occurred.
event_fd_readwrite
event_proc_terminate
eventrwflags: The state of the file descriptor subscribed to with FD_READ or FD_WRITE.
fd: A file descriptor number.
fdflags: File descriptor flags.
fdsflags: Which file descriptor attributes to adjust.
fdstat: File descriptor attributes.
filestat: File attributes.
fsflags: Which file attributes to adjust.
inode: File serial number that is unique within its file system.
iovec: A region of memory for scatter/gather reads.
lock: A userspace read-recursive readers-writer lock, similar to a Linux futex or a FreeBSD umtx.
lookup: Path lookup properties.
lookupflags: Flags determining the method of how paths are resolved.
mflags: Memory mapping flags.
mprot: Memory page protection options.
msflags: Methods of synchronizing memory with physical storage.
oflags: Open flags used by file_open().
recv_in: Arguments of sock_recv().
recv_out: Results of sock_recv().
riflags: Flags provided to sock_recv().
rights: File descriptor rights, determining which actions may be performed.
roflags: Flags returned by sock_recv().
sdflags: Which channels on a socket need to be shut down.
send_in: Arguments of sock_send().
send_out: Results of sock_send().
siflags: Flags provided to sock_send(). As there are currently no flags defined, it must be set to zero.
subclockflags: Flags determining how the timestamp provided in subscription.union.clock.timeout should be interpreted.
subrwflags: Flags influencing the method of polling for read or writing on a file descriptor.
subscription: Subscription to an event.
subscription_clock
subscription_condvar
subscription_fd_readwrite
subscription_lock
subscription_proc_terminate
tcb: The Thread Control Block (TCB).
threadattr: Attributes for thread creation.
tid: Unique system-local identifier of a thread. This identifier is only valid during the lifetime of the thread.
ulflags: Specifies whether files are unlinked or directories are removed.

Enums§

advice: File or memory access pattern advisory information.
auxtype: Enumeration describing the kind of value stored in auxv.
clockid: Identifiers for clocks.
errno: Error codes returned by system calls.
eventtype: Type of a subscription to an event or its occurrence.
filetype: The type of a file descriptor or file.
scope: Indicates whether an object is stored in private or shared memory.
signal: Signal condition.
whence: Relative to which position the offset of the file descriptor should be set.

Constants§

CONDVAR_HAS_NO_WAITERS: The condition variable is in its initial state. There are no threads waiting to be woken up. If the condition variable has any other value, the kernel must be called to wake up any sleeping threads.
DIRCOOKIE_START: Permanent reference to the first directory entry within a directory.
LOCK_BOGUS: Value indicating that the lock is in an incorrect state. A lock cannot be in its initial unlocked state, while also managed by the kernel.
LOCK_KERNEL_MANAGED: Bitmask indicating that the lock is either read locked or write locked, and that one or more threads have their execution suspended, waiting to acquire the lock. The last owner of the lock must call the kernel to unlock.
LOCK_UNLOCKED: Value indicating that the lock is in its initial unlocked state.
LOCK_WRLOCKED: Bitmask indicating that the lock is write-locked. If set, the lower 30 bits of the lock contain the identifier of the thread that owns the write lock. Otherwise, the lower 30 bits of the lock contain the number of acquired read locks.
MAP_ANON_FD: Passed to mem_map() when creating a mapping to anonymous memory.
PROCESS_CHILD: Returned to the child process by proc_fork().

Functions§

clock_res_get^⚠: Obtains the resolution of a clock.
clock_time_get^⚠: Obtains the time value of a clock.
condvar_signal^⚠: Wakes up threads waiting on a userspace condition variable.
fd_close^⚠: Closes a file descriptor.
fd_create1^⚠: Creates a file descriptor.
fd_create2^⚠: Creates a pair of file descriptors.
fd_datasync^⚠: Synchronizes the data of a file to disk.
fd_dup^⚠: Duplicates a file descriptor.
fd_pread^⚠: Reads from a file descriptor, without using and updating the file descriptor’s offset.
fd_pwrite^⚠: Writes to a file descriptor, without using and updating the file descriptor’s offset.
fd_read^⚠: Reads from a file descriptor.
fd_replace^⚠: Atomically replaces a file descriptor by a copy of another file descriptor.
fd_seek^⚠: Moves the offset of the file descriptor.
fd_stat_get^⚠: Gets attributes of a file descriptor.
fd_stat_put^⚠: Adjusts attributes of a file descriptor.
fd_sync^⚠: Synchronizes the data and metadata of a file to disk.
fd_write^⚠: Writes to a file descriptor.
file_advise^⚠: Provides file advisory information on a file descriptor.
file_allocate^⚠: Forces the allocation of space in a file.
file_create^⚠: Creates a file of a specified type.
file_link^⚠: Creates a hard link.
file_open^⚠: Opens a file.
file_readdir^⚠: Reads directory entries from a directory.
file_readlink^⚠: Reads the contents of a symbolic link.
file_rename^⚠: Renames a file.
file_stat_fget^⚠: Gets attributes of a file by file descriptor.
file_stat_fput^⚠: Adjusts attributes of a file by file descriptor.
file_stat_get^⚠: Gets attributes of a file by path.
file_stat_put^⚠: Adjusts attributes of a file by path.
file_symlink^⚠: Creates a symbolic link.
file_unlink^⚠: Unlinks a file, or removes a directory.
lock_unlock^⚠: Unlocks a write-locked userspace lock.
mem_advise^⚠: Provides memory advisory information on a region of memory.
mem_map^⚠: Creates a memory mapping, making the contents of a file accessible through memory.
mem_protect^⚠: Change the protection of a memory mapping.
mem_sync^⚠: Synchronize a region of memory with its physical storage.
mem_unmap^⚠: Unmaps a region of memory.
poll^⚠: Concurrently polls for the occurrence of a set of events.
proc_exec^⚠: Replaces the process by a new executable.
proc_exit^⚠: Terminates the process normally.
proc_fork^⚠: Forks the process of the calling thread.
proc_raise^⚠: Sends a signal to the process of the calling thread.
random_get^⚠: Obtains random data from the kernel random number generator.
sock_recv^⚠: Receives a message on a socket.
sock_send^⚠: Sends a message on a socket.
sock_shutdown^⚠: Shuts down socket send and receive channels.
thread_create^⚠: Creates a new thread within the current process.
thread_exit^⚠: Terminates the calling thread.
thread_yield^⚠: Temporarily yields execution of the calling thread.

Type Aliases§

exitcode: Exit code generated by a process when exiting.
filedelta: Relative offset within a file.
filesize: Non-negative file size or length of a region within a file.
linkcount: Number of hard links to an inode.
nthreads: Specifies the number of threads sleeping on a condition variable that should be woken up.
processentry: Entry point for a process (_start).
threadentry: Entry point for additionally created threads.
timestamp: Timestamp in nanoseconds.
userdata: User-provided value that can be attached to objects that is retained when extracted from the kernel.

Unions§

auxv_union: A union inside auxv.
event_union: A union inside event.
subscription_union: A union inside subscription.

Crate cloudabiCopy item path