Crate cloudabi [−] [src]
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:
- Arch Linux
- Debian, Ubuntu, and other Debian derivatives
- FreeBSD, PC-BSD and DragonFly BSD
- Mac OS X
- NetBSD
Specification of the ABI
The entire ABI is specified in a 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 |
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 |
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 |
recv_in |
Arguments of |
recv_out |
Results of |
riflags |
Flags provided to |
rights |
File descriptor rights, determining which actions may be performed. |
roflags |
Flags returned by |
sdflags |
Which channels on a socket need to be shut down. |
send_in |
Arguments of |
send_out |
Results of |
siflags |
Flags provided to |
subclockflags |
Flags determining how the timestamp provided in
|
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 |
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 |
PROCESS_CHILD |
Returned to the child process by |
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 Definitions
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 ( |
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 |
event_union |
A union inside |
subscription_union |
A union inside |