room.1.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="room.1">

<refmeta>
<refentrytitle>room</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
<refname>room</refname>
<refpurpose>manage rooms</refpurpose>
</refnamediv>

<refsect1><title>SYNOPSIS</title>

<para>
<literallayout>
<emphasis role="bold">room</emphasis> <emphasis role="bold">build</emphasis> <replaceable>path</replaceable>
<emphasis role="bold">room</emphasis> <emphasis role="bold">clone</emphasis> <replaceable>source</replaceable> [<replaceable>destination</replaceable>]
<emphasis role="bold">room list</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">configure</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">create</emphasis> [options] [--clone <replaceable>room-name</replaceable>] [--archive <replaceable>path</replaceable>]
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">destroy</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">enter</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">exec</emphasis> [-u <replaceable>user</replaceable>] <emphasis role="bold">--</emphasis> <replaceable>command [arguments]</replaceable>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">snapshot</emphasis> <replaceable>snapshot-name</replaceable> create
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">snapshot</emphasis> <replaceable>snapshot-name</replaceable> destroy
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">snapshot list</emphasis><!--
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">receive</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">send</emphasis>-->
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">pull</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">push</emphasis> [-u|--set-upstream <replaceable>URI</replaceable>]
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">start</emphasis>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">stop</emphasis>
</literallayout>
</para>
</refsect1>


<refsect1><title>Description</title>
<para>
The <command>room</command> command is the management utility
for rooms. Rooms are a simplified form of containers that are
built on top of ZFS and FreeBSD jails.
</para>

<para>
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. 
</para>

<para>
The following subcommands and options are available:
</para>
	
<variablelist>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <emphasis role="bold">build</emphasis> <replaceable>path</replaceable>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Build a room from source code using a configuration file at a given <replaceable>path</replaceable>.
	The format of the configuration file is described in
	<citerefentry><refentrytitle>Roomfile</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 
			</para>
		</listitem>
	</varlistentry>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <emphasis role="bold">clone</emphasis> <replaceable>source</replaceable> [<replaceable>destination</replaceable>]
</literallayout>
		</term>
	
		<listitem>
			<para>
	Create a clone of the given <replaceable>source</replaceable> room, which may be the URI to a remote
	room, or the name of a local room. When cloning a remote room, you can optionally 
	provide a different [<replaceable>destination</replaceable>] name for
	the room; if none is provided, the last component of the URI will be used. 
			</para>
		</listitem>
	</varlistentry>


	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room list</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	List all existing rooms. The name of each room will be printed, one per line.
			</para>
		</listitem>
	</varlistentry>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">configure</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Edit the configuration settings for a room named <replaceable>source</replaceable>.
	FIXME: each setting should be documented here.
			</para>
		</listitem>
	</varlistentry>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">create</emphasis> [options] [--clone <replaceable>room-name</replaceable>] [--archive <replaceable>path</replaceable>]
</literallayout>
		</term>
	
		<listitem>
	<para>
	Create a new room called <replaceable>name</replaceable>.
	</para>
	
	<para>
	If the <replaceable>--archive</replaceable> option is provided, the 
	tar(1) formatted archive will be extracted into the root filesystem of the room.
	</para>

	<para>
	If the <replaceable>--clone</replaceable> option is provided, the 
	room will be cloned from an existing room whose name matches
	<replaceable>room-name</replaceable>. 
	</para>
	
	<para>
	Refer to the <emphasis role="bold">CONFIGURATION OPTIONS</emphasis> section
	for a list of the options that can be set. 
	</para>

		</listitem>
	</varlistentry>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">destroy</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Permanently delete the room called <replaceable>name</replaceable>. All processes running
	in the room will be forcefully terminated. The data for the room will be removed.
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">enter</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Invoke a login shell inside the room called <replaceable>name</replaceable>.
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">exec</emphasis> [-u <replaceable>user</replaceable>] <emphasis role="bold">--</emphasis> <replaceable>command [arguments]</replaceable>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Execute the given <replaceable>command</replaceable> inside the room called <replaceable>name</replaceable>.
	By default, commands will be executes as the current user. To run commands as a different user
	pass the <replaceable>-u</replaceable> or <replaceable>--user</replaceable> 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.
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">pull</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
			Downloads new versions of the room from the remote repository,
			and fast-forwards the room to the latest version.
			</para>
			
			<para>
			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.
			</para>
					
			<para>
			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.
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">push</emphasis> [-u|--set-upstream <replaceable>URI</replaceable>]
</literallayout>
		</term>
	
		<listitem>
			<para>
			Pushes the latest versions of the room to the remote repository.
			New versions may be created using the "room snapshot" command.
			</para>

			<para>
			This command only works on rooms that have an "origin" URI defined. 
			To set the origin URI, use the --set-upstream <replaceable>URI</replaceable> option. 
			The only support transport at this time is SSH, so URIs must be in the format <replaceable>ssh://$FQDN/$PATH</replaceable>.
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">start</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Start up a room with the given <replaceable>name</replaceable>.
	Currently, this will mount filesystems and create a jail. In the future,
	support will be added for starting programs automatically within the room. 
			</para>
		</listitem>
	</varlistentry>	

<!--
	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">receive</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Create a room with the given <replaceable>name</replaceable> from
	a streaming archive provided over standard input. The archive must
	be created by running the "room send" command. 
	This behaves similar to the "zfs receive" command. 
			</para>
		</listitem>
	</varlistentry>	

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">send</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Create a streaming archive of a room with the given <replaceable>name</replaceable> and 
	send it to standard output. This behaves similar to the "zfs send" command. 
			</para>
		</listitem>
	</varlistentry>	

-->
	
		<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">room</emphasis> <replaceable>name</replaceable> <emphasis role="bold">stop</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Terminate all processes inside the room called <replaceable>name</replaceable>,
	unmount all mounted filesystems in the room, and destroy the associated jail. 
			</para>
		</listitem>
	</varlistentry>	
	
</variablelist>

</refsect1>

<refsect1>
<title>CONFIGURATION OPTIONS</title>
<para>
When creating a new room, there are a number of configuration
options that can be specified:
</para>

<variablelist>

	<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">--allow-x11</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Allows programs in the room to run graphical X11 clients.
	This also grants access to the D-Bus user session. 
			</para>
			<para>
			By default, rooms do not have access to run graphical programs
			on the local host.
			</para>
		</listitem>
	</varlistentry>
	
		<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">--share-tempdir</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	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.
			</para>
			<para>
			By default, each room has a private /tmp and /var/tmp.
			</para>
		</listitem>
	</varlistentry>

		<varlistentry>
		<term>
<literallayout>
<emphasis role="bold">--share-home</emphasis>
</literallayout>
		</term>
	
		<listitem>
			<para>
	Mounts the user's home directory inside of the room.
			</para>
			<para>
			By default, each room has a private home directory
			that is not shared with the main system or any other room.
			</para>
		</listitem>
	</varlistentry>
	
</variablelist>

</refsect1>

<refsect1>
	<title>EXAMPLES</title>
	<para>
	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.
	</para>
	<programlisting>
<![CDATA[
$ room FreeBSD-11.0-RELEASE create \
    --uri=ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/amd64/11.0-RELEASE/base.txz
]]>
	</programlisting>

	<para>
	The following example clones a room named "FreeBSD-11.0" from
	a remote repository. 
	</para>
	<programlisting>
	<![CDATA[
$ room clone http://example.com/rooms/FreeBSD-11.0
]]>
	</programlisting>
	
	<para>
	The following example clones the FreeBSD-11.0 room and call it "myroom".
	</para>
	<programlisting>
<![CDATA[
$ room clone FreeBSD-11.0 myroom 
]]>
	</programlisting>

<!--
	<para>
	To copy a room called "FreeBSD-10.3" to a remote server named "myhost".
	</para>
	<programlisting>
<![CDATA[
$ room FreeBSD-10.3 send | ssh myhost room receive FreeBSD-10.3
]]>
	</programlisting>
 -->
 
</refsect1>

<refsect1>
	<title>ENVIRONMENT</title>
	<para>
	The <command>room</command> command does not rely on any environment variables.
	</para>
</refsect1>

<refsect1>
	<title>EXIT STATUS</title>
	<para>
	The <command>room</command> command exits 0 on success, and >0 if an error occurs
	</para>
</refsect1>

<refsect1>
	<title>SEE ALSO</title>
	<para>
	<citerefentry><refentrytitle>Roomfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> 
	</para>
</refsect1>

<refsect1>
	<title>AUTHORS</title>
	<para>
		Mark Heily &lt;mark@heily.com&gt;
	</para>
</refsect1>

<refsect1>
	<title>BUGS</title>
	
	<!-- 
	<para>
	Sending and receiving rooms will not work as expected if you are operating on
	rooms which are clones.  
	</para>
	 -->

	<para>
	The "pull" command is not yet implemented.
	</para>

	<para>
	The snapshot subcommands are not documented in this manual page.
	</para>
</refsect1>

</refentry>