room — manage rooms
room list
room name clone URI
room name configure
room name create [options] [--clone room-name] [--uri URI]
room name destroy
room name enter
room name exec [-u user] -- command [arguments]
room name snapshot snapshot-name create
room name snapshot snapshot-name destroy
room name snapshot list
room name pull
room name push
room name start
room name stop
The room command is the management utility for rooms. Rooms are a simplified form of containers that are built on top of ZFS and FreeBSD jails.
Rooms are composed of two separate parts: shared and local. The shared part of the room is writable, but any changes will be lost when the room is upgraded to a newer version. The local part of the room is mounted at /data, and should be used to hold data that needs to persist after an upgrade. It is strongly encouraged that room developers use symbolic links to redirect important files and directories to /data; even better would be to build applications to store their variable data under /data rather than the traditional /var.
The following subcommands and options are available:
room list
List all existing rooms. The name of each room will be printed, one per line.
room name configure
Edit the configuration settings for a room named source.
FIXME: each setting should be documented here.
room name clone URI
Clone a room from a remote URI. If a new version
of the remote room is published, you can run the "room pull" command to
download the latest version.
room name create [options] [--clone room-name] [--uri URI]
Create a new room called name.
If the --uri option is provided, the URI will be
downloaded and extracted into the root filesystem of the room.
If the --clone option is provided, the
room will be cloned from an existing room whose name matches
room-name.
Refer to the CONFIGURATION OPTIONS section for a list of the options that can be set.
room name destroy
Permanently delete the room called name. All processes running
in the room will be forcefully terminated. The data for the room will be removed.
room name enter
Invoke a login shell inside the room called name.
room name exec [-u user] -- command [arguments]
Execute the given command inside the room called name.
By default, commands will be executes as the current user. To run commands as a different user
pass the -u or --user option along with the name or numeric ID of the user.
To avoid confusion, it is recommended to use -- to signify the start of the command(s) to be executed.
room name pull
Downloads new versions of the room from the remote repository, and fast-forwards the room to the latest version.
This is a potentially dangerous operation. Any programs running in the room will be forefully terminated. Changes to files outside of the /home and /data directories within the room will be lost. Rooms are designed to store data in a persistent location, but there is a chance that users may have accidentally stored files outside of the designated safe areas. In the future, this subcommand will run a "zfs diff" and alert the user if files would be deleted as a result of the pull opreration.
This command only works on rooms that were cloned from a remote repository via the "room clone" command. If the room was created locally via the "room create" command, there is no remote repository to pull from.
room name push
Pushes the latest versions of the room to the remote repository. New versions may be created using the "room snapshot" command.
This command only works on rooms that have an "origin" URI defined in their configuration file. The only supported transport mechanism at this time is SSH.
room name start
Start up a room with the given name.
Currently, this will mount filesystems and create a jail. In the future,
support will be added for starting programs automatically within the room.
room name stop
Terminate all processes inside the room called name,
unmount all mounted filesystems in the room, and destroy the associated jail.
When creating a new room, there are a number of configuration options that can be specified:
--allow-x11
Allows programs in the room to run graphical X11 clients. This also grants access to the D-Bus user session.
By default, rooms do not have access to run graphical programs on the local host.
--share-tempdir
Mounts the /tmp and /var/tmp directories from the main host inside the room. This may be necessary for programs that use files inside of /tmp for inter-process communication.
By default, each room has a private /tmp and /var/tmp.
--share-home
Mounts the user's home directory inside of the room.
By default, each room has a private home directory that is not shared with the main system or any other room.
The following example creates a room containing the base install of FreeBSD 11.0. An empty room is created, the base tarball is downloaded from the FTP mirror site, and the tarball is extracted to create a fresh install.
$ room FreeBSD-11.0-RELEASE create \
--uri=ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/11.0-RELEASE/base.txz
The following example clones a room named "FreeBSD-11.0-RELEASE" from a remote repository.
$ room FreeBSD-11.0-RELEASE clone http://arise.daemonspawn.org/rooms/FreeBSD-11.0-RELEASE
Clone the FreeBSD-10.3 room and call it "myroom".
$ room myroom create --clone FreeBSD-10.3