vera.xml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<article id="index.html">
  <sect1 id="INSTALL">
    <title>INSTALL</title>
    <para>
      The requirements to build <command>vera</command> are:
    </para>

    <itemizedlist>
      <listitem>
	<para>
	  gcc 11 or higher
	</para>
      </listitem>

      <listitem>
	<para>
	  <application>libyaml</application>
	</para>
      </listitem>
    </itemizedlist>

    <para>
      To compile and install <command>vera</command> from source execute the
      <command>configure</command> script with these recommended options:
    </para>

    <blockquote>
      <informalexample>
	<programlisting>./configure --prefix=/usr --sysconfdir=/etc --sbindir=/sbin \&#10;    --libdir=/lib --localstatedir=/run \&#10;    --with-switchlogdir=/var/log/vera\&#10;    --localedir=/usr/share/locale</programlisting>
      </informalexample>
    </blockquote>

    <para>
      This installs <command>vera</command> and <command>vlad</command> commands
      into <filename>/sbin</filename>, the unit configuration file directory
      gets created in <filename>/lib/vera</filename>; the local
      unit configuration overrides and other configuration files in
      <filename>/etc/vera</filename>, and the runtime sockets in
      <filename>/run</filename>.
    </para>

    <para>
      If <filename>/usr/local</filename> is not a separate, mounted partition,
      if it's on a root partition, running <command>./configure</command>
      without any options installs everything into
      <filename>/usr/local</filename>.
    </para>

    <para>
      Next, execute:
    </para>

    <blockquote>
      <informalexample>
	<programlisting>make [-j #]</programlisting>
      </informalexample>
    </blockquote>

    <para>
      to build <command>vera</command>.
    </para>

    <para>
      Execute:
    </para>
    <blockquote>
      <informalexample>
	<programlisting>make install DESTDIR=/tmp/tmp-inst</programlisting>
      </informalexample>
    </blockquote>
    <para>
      this creates
      an installation image in <filename>/tmp/tmp-inst</filename>, this shows
      where everything gets installed.
    </para>

    <para>
      <quote><command>make install</command></quote> runs a script that
      reads <filename>/etc/inittab</filename> and
      <filename>/etc/rc.d/rc?.d</filename> and converts them
      to <command>vera</command>'s unit specifications. The script fails
      if it doesn't understand them.
      The user id that runs <command>make install</command> must have access
      to <filename>/etc/inittab</filename> and
      <filename>/etc/rc.d/rc?.d</filename>.
    </para>

    <para>
      After verifying the correct installation paths, execute
    </para>

    <blockquote>
      <informalexample>
	<programlisting>sudo make install</programlisting>
      </informalexample>
    </blockquote>
    <para>
      This installs <command>vera</command> but does not replace
      <command>init</command>. To do that execute (as root):
    </para>

    <blockquote>
      <informalexample>
	<programlisting>vlad hookonce</programlisting>
      </informalexample>
    </blockquote>

    <para>
      and reboot. This
      triggers only the next reboot into <command>vera</command> so that
      if there's any issue then forcing another reboot will reboot with
      <command>init</command>.
    </para>

    <para>
      After
      rebooting run
    </para>

    <blockquote>
      <informalexample>
	<programlisting>vlad status</programlisting>
      </informalexample>
    </blockquote>

    <para>
      to see all containers
      that were started for converted <filename>/etc/inittab</filename>
      entries. Run
    </para>

    <blockquote>
      <informalexample>
	<programlisting>vlad hook</programlisting>
      </informalexample>
    </blockquote>
    <para>
      to have all future reboots use
      <command>vera</command>.
    </para>

    <note>
      <para>
	Do not update <command>sysvinit</command> or
	<command>logrotate</command> after installing
	<command>vera</command>. If you would like to go back to
	<command>init</command>, or to update:
      </para>

      <itemizedlist>
	<listitem>
	  <para>Run <quote><command>vlad unhook</command></quote>.</para>
	</listitem>

	<listitem>
	  <para>
	    Reboot, this will boot with <command>init</command>.
	    IMPORTANT: run
	    <quote><command>vlad unhook</command></quote> a second time.
	  </para>
	</listitem>
      </itemizedlist>
    </note>

    <para>
      See the <citerefentry>
      <refentrytitle>vera</refentrytitle>
      <manvolnum>8</manvolnum>
      </citerefentry> manual page for more information.
    </para>

    <note>
      <para>
	<command>vera</command> does not replace
	the <quote><command>shutdown</command></quote> and
	<quote><command>reboot</command></quote> commands from sysvinit.
	They're still used with <command>vera</command>.
      </para>
    </note>

    <sect2 id="slackpkg">
      <title>Slackware64 package</title>

      <para>
	The Slackware package installs vera with the default configuration
	options. The package's installation script automatically
	runs the <quote>inittab</quote> command that reads
	<filename>/etc/inittab</filename> and
	<filename>/etc/rc.d/rc?.d</filename> and converts them
	to <command>vera</command>'s unit specifications. The script fails
	if it doesn't understand them.
	Install the Slackware 15 package with
	<quote><command>installpkg</command></quote>
	and follow the instructions above starting with the
	<quote><command>vlad hookonce</command></quote>
	command.
      </para>
      <note>
	<para>
	  Before using <command>removepkg</command> to uninstall
	  <command>vera</command>, or before updating
	  <command>sysvinit</command> or <command>logrotate</command>
	  packages, the following command must be executed:
	</para>

	<blockquote>
	  <informalexample>
	    <programlisting>vlad unhook</programlisting>
	  </informalexample>
	</blockquote>

	<para>
	  followed by a reboot and ANOTHER <quote>vlad unhook</quote>
	  command.
	</para>
      </note>

      <para>
	See the <citerefentry>
	<refentrytitle>vera</refentrytitle>
	<manvolnum>8</manvolnum>
	</citerefentry> manual page for more information.
      </para>
    </sect2>

    <sect2 id="issues">
      <title>Known issues on Slackware 15</title>

      <para>
	Shutdowns take a few more seconds to complete.
	 <quote><filename>/etc/rc.d/rc.M</filename></quote> runs
	 <quote><literal>/etc/rc.d/rc.script start</literal></quote> commands,
	 but
	 <quote><filename>/etc/rc.d/rc.K</filename></quote> runs only
	 a handful of
	 <quote><literal>/etc/rc.d/rc.script stop</literal></quote>s, and
	 skips most of them.
	 <quote><filename>/etc/rc.d/rc.K</filename></quote> takes the easy
	 way out that simply
	 <command>kilall</command>s all processes.
      </para>

      <para>
	<quote><command>vera inittab</command></quote> converts each
	<quote><command>rc.script</command></quote> to a unit,
	and the unit formally runs
	<quote><command>rc.script start</command></quote> and
	<quote><command>rc.script stop</command></quote>.
	Stopping each unit takes additional
	time.
	This also exposes a
	<quote><command>rc.networkmanager</command></quote> issue
	with its default DHCP configuration that uses
	<command>dhcpcd</command>: there's a ten second delay in the
	middle of every shutdown, with <command>vera</command> waiting for
	one <command>dhcpcd</command> process to stop. This appears to be
	a <command>dhcpcd</command> glitch.
	This gets covered up normally by <command>rc.K</command> terminating
	all processes at once, but gets exposed when NetworkManager runs in
	a container.
      </para>

      <para>
	This does not happen with
	<quote><literal>dhcp=dhclient</literal></quote> in
	<filename>/etc/NetworkManager/conf.d/00-dhcp-client.conf</filename>.
      </para>
    </sect2>
  </sect1>
  <sect1 id="manpages">
    <title>Manual pages</title>

    <refentry id="vera.8">

      <refmeta>
	<refentrytitle>vera</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo>Double Precision, Inc.</refmiscinfo>
      </refmeta>

      <refnamediv>
	<refname>vera</refname>
	<refname>vlad</refname>
	<refname>init</refname>
	<refpurpose>Linux process supervisor</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<cmdsynopsis>
	  <command>vlad</command>
	  <group choice='req'>
	    <arg choice='plain'>reexec</arg>
	    <arg choice='plain'>vera-up</arg>
	    <arg choice='plain'>hook</arg>
	    <arg choice='plain'>hookonce</arg>
	    <arg choice='plain'>unhook</arg>
	    <arg choice='plain'>inittab</arg>
	    <arg choice='plain'>rehook</arg>
	  </group>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <arg rep='repeat'>parameter</arg>
	</cmdsynopsis>
	<blockquote>
	  <para>
	    Internal commands:
	  </para>
	</blockquote>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>sysdown</arg>
	  <arg choice='req'>runlevel</arg>
	  <arg choice='req'>script</arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vera-init</command>
	  <arg choice='opt' rep='repeat'>parameter</arg>
	</cmdsynopsis>
      </refsynopsisdiv>

      <refsect1 id="description">
	<title>DESCRIPTION</title>

	<para>
	  The <command>vera</command> system process runs as PID 1 and is
	  responsible for starting and stopping major system processes, including
	  system startup and shutdown. <command>vera</command> also listens on
	  an internal socket for commands that adjust the system running state.
	  The <command>vlad</command> command connects to that internal
	  socket and passes along the commands (that <command>vlad</command>
	  doesn't handle by itself).
	</para>

	<para>
	  Installing <command>vera</command> does not automatically replace
	  the default <command>init</command>
	  supervisor. This manual page describes the process
	  for converting an existing system from <command>init</command> to
	  <command>vera</command>, and restoring a converted system back to
	  <command>init</command>. This manual page also describes some common
	  and less common management commands.
	</para>

	<para>
	  See
	  <link linkend="vera.runlevels.8">
	    <citerefentry>
              <refentrytitle>vera.runlevels</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link> for a description of how <command>vera</command> manages
	    runlevels, starts, and stops individual units or processes.
	</para>

	<para>
	  See
	  <link linkend="vera.units.8">
	    <citerefentry>
              <refentrytitle>vera.units</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link> for more information on adding custom units and
	    processes to <command>vera</command>.
	</para>

	<para>
	  See
	  <link linkend="vera.logs.8">
	    <citerefentry>
              <refentrytitle>vera.logs</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	  </link>
	  for more information on obtaining basic statistics on processes
	  started by <command>vera</command>.
	</para>

	<para>
	  See
	  <link linkend="vera.extras.8">
	    <citerefentry>
              <refentrytitle>vera.extras</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	  </link>
	  for more information on additional features that
	  <command>vera</command> adds to a base Slackware system.
	</para>
      </refsect1>

      <refsect1 id="management">
	<title>MANAGING <command>vera</command></title>
	<para>
	  <quote>reexec</quote> signals the <command>vera</command> system
	  process to restart itself. This is needed after installing a new
	  version of <command>vera</command> or one of the system libraries
	  it uses (the system was already converted to run
	  <command>vera</command> instead of <command>init</command> and
	  a new version of <command>vera</command> was installed).
	  It's possible that <command>vera</command> will not
	  restart immediately. If any units are in the middle of being
	  stopped, started, restarted, or respawned a
	  <quote>reexec</quote> gets delayed until
	  all pending activity finishes.
	</para>

	<note>
	  <para>
	    The Slackware package takes care of running <quote>reexec</quote>
	    when installing a package update.
	  </para>
	</note>

	<note>
	  <para>
	    This can be a lengthy delay when there's a respawned unit that
	    reached its maximum number of attempts and it's waiting until
	    it's respawnable.
	    Additionally, <quote>reexec</quote> resets all respawned units'
	    counters and limits.
	  </para>

	  <para>
	    This is not considered critical, a <quote>reexec</quote> is
	    not something that normally happens.
	  </para>
	</note>

	<para>
	  <command>vlad vera-up</command> tries to connect to
	  <command>vera</command>'s public socket. A successful connection
	  indicates that <command>vera</command> is installed and
	  running. This is indicated by a 0 exit code.
	  A connection failure is reported by terminating with a non-0
	  exit code (no error message is shown).
	</para>

	<para>
	  Installing <command>vera</command> (from a package or by
	  <command>make install</command>) does not touch or replace the
	  default system <command>init</command> daemon. Additional commands
	  must be executed, and a coordinated reboot is required in order to
	  roll the dice, and start <command>vera</command>.
	</para>

	<para>
	  The <command>hook</command> and <command>hookonce</command> commands
	  begin the process of converting from <command>init</command> to
	  <command>vera</command>. They make the following changes:
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      The original <filename>/sbin/init</filename> gets moved to
	      <filename>/sbin/init.init</filename>.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The original
	      <filename>/etc/rc.d/rc.sysvinit</filename>,
	      <filename>/etc/rc.d/rc.local</filename> and
	      <filename>/etc/rc.d/rc.local_shutdown</filename>,
	      scripts get moved to
	      <filename>/etc/rc.d/rc.sysvinit.init</filename>,
	      <filename>/etc/rc.d/rc.local.init</filename> and
	      <filename>/etc/rc.d/rc.local_shutdown.init</filename>,
	      if they exist.
	      The original <filename>/usr/sbin/logrotate</filename> binary
	      gets moved to <filename>/usr/sbin/logrotate.init</filename>.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The moved scripts and binaries get replaced
	      with links to <command>vera</command>'s replacements.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      <filename>@CONFIGDIR@/hook</filename> gets created.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>
	  The installed rc script replacements check if
	  <command>vera-up</command>,
	  if so they do nothing because the <command>inittab</command>
	  command installs units that
	  run these scripts and commands.
	  Otherwise, if not <command>vera-up</command> and
	  <command>init</command>
	  is still running (prior/after a reboot) the
	  replacements execute the replaced program or script, with no
	  change in behavior.
	</para>

	<para>
	  The replacement <command>/usr/sbin/logrotate</command> script
	  checks if <command>vera-up</command>, if so then the original
	  <command>/usr/sbin/logrotate.init</command> runs with a different
	  configuration, <filename>/etc/logrotate.conf.vera</filename>.
	  Otherwise, if not <command>vera-up</command> and
	  <command>init</command>
	  is still running (prior/after a reboot) then
	  <command>/usr/sbin/logrotate.init</command> runs with the default
	  <filename>/etc/logrotate.conf</filename> configuration.
	</para>

	<para>
	  An installed container, <filename>system/update-logrotate</filename>
	  runs a script when the system boot. This script reads
	  <filename>/etc/logrotate.conf</filename> and
	  <filename>/etc/logrotate.d</filename>, and creates
	  <filename>/etc/logrotate.conf.vera</filename> and
	  <filename>/etc/logrotate.d.vera</filename>. Every reference in
	  logrotate's scripts that runs
	  <filename>/etc/rc.d/<replaceable>name</replaceable> restart</filename>
	  or
	  <filename>/etc/rc.d/<replaceable>name</replaceable> reload</filename>
	  gets replaced with the equivalent <command>vlad</command> command.
	</para>

	<para>
	  The replacement <command>/sbin/init</command>, called
	  <command>vera-init</command>, checks that
	  <filename>@CONFIGDIR@/hook</filename> exists on the next reboot, and
	  starts <command>vera</command> instead of the replaced
	  <command>init</command>.
	</para>

	<para>
	  <command>hookonce</command> results in the removal of
	  <filename>@CONFIGDIR@/hook</filename> on the next reboot as early
	  as possible. Its absence on a subsequent reboot results in the
	  original <command>init</command> (now
	  <filename>/sbin/init.init</filename>) starting normally as PID 1.
	</para>

	<para>
	  The <command>unhook</command> command manually removes
	  <filename>@CONFIGDIR@/hook</filename> and if the system was booted
	  with <command>vera</command> no further action is taken.
	  A reboot is required to start the system with the original
	  <command>init</command> then the <command>unhook</command> command
	  gets executed a second time. This
	  completes the process of reverting back to
	  <command>init</command>.
	</para>

	<para>
	  When <command>unhook</command> determines that
	  <command>vera-up</command> is not the case, <command>unhook</command>
	  restores the scripts and binaries
	  that <command>hook</command> originally moved.
	</para>

	<note>
	  <para>
	    Do not run <command>make uninstall</command> to completely
	    uninstall <command>vera</command> unless it's fully unhooked.
	  </para>

	  <para>
	    Do not update <command>sysvinit</command> and
	    <command>logrotate</command>
	    unless
	    <command>vera</command> is fully unhooked.
	  </para>
	</note>

	<para>
	  The <command>inittab</command> command
	  rereads <filename>/etc/inittab</filename>,
	  <filename>/etc/rc.d/rc.M</filename>,
	  and <filename>/etc/rc.d/rc?.d</filename> directories,
	  the translates them to unit specification files in
	  <filename>@INSTALLCONFIGDIR@</filename>. A brief overview
	  of the translation process for entries in the
	  <filename>/etc/inittab</filename> file:
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      All <quote><replaceable>keyword</replaceable>wait</quote>
	      entries get created as <quote>forking</quote> start types;
	      <quote>respawn</quote> as <quote>respawn</quote>; and
	      all others as <quote>oneshot</quote>.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <quote>power<replaceable>state</replaceable></quote>,
	      <quote>ctrlaltdel</quote>, and
	      <quote>boot</quote> are added to the corresponding
	      target.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <quote>boot</quote> and
	      <quote>bootwait</quote>
	      entries get added as dependencies of
	      <filename>system/boot</filename> which is a dependency of
	      all runlevels, in this manner these entries get executed
	      before all runlevels' entries.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Each entry's one-character runlevels get converted to the
	      corresponding <command>vera</command> runlevel targets,
	      and the entry becomes a dependency of the runlevel target.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Entries that match the names of selected
	      <filename>/etc/rc.d/rc.<replaceable>X</replaceable></filename>
	      scripts get singled out for special processing.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <quote>Before</quote> and <quote>After</quote>
	      get specified for each converted inittab, that starts them
	      (and stops them in reverse order) in order of appearance
	      in <filename>/etc/inittab</filename>.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The
	      <filename>@INSTALLCONFIGDIR@/system/inittab</filename>
	      directory gets created or updated with units that run each
	      <filename>/etc/inittab</filename> entry.
	    </para>
	  </listitem>
	</itemizedlist>

	<note>
	  <para>
	    Changes to the <quote>initdefault</quote> entry are ignored.
	    Use the
	    <command>default</command> command to change the default
	    runlevel (see
	    <link linkend="vera.runlevels.8">
	      <citerefentry>
		<refentrytitle>vera.runlevels</refentrytitle>
		<manvolnum>8</manvolnum>
	      </citerefentry>
	      </link>).
	  </para>
	</note>

	<para>
	  The <filename>/etc/rc.d/rc.M</filename> script's contents are
	  searched for every instance of
	  <quote>-x /etc/rc.d/<replaceable>rc.script</replaceable></quote>
	  followed by
	  <quote>/etc/rc.d/<replaceable>rc.script</replaceable>
	  start</quote>.
	  This creates a corresponding
	  <filename>@INSTALLCONFIGDIR@/system/rc.M/<replaceable>rc.script</replaceable></filename>
	  unit that runs
	  <quote>/etc/rc.d/<replaceable>rc.script</replaceable> start</quote>
	  and
	  <quote>/etc/rc.d/<replaceable>rc.script</replaceable> stop</quote>.
	  The entry for <filename>/etc/rc.d/rc.M</filename> executes it via
	  a wrapper that converts it, on the fly,
	  to start each corresponding unit, instead of running each script
	  directly.
	</para>

	<para>
	  Finally, entries in <filename>/etc/rc.d/rc?.d</filename>
	  get translated to unit files as follows:
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      All files with names that don't start with
	      <quote>S</quote> and <quote>K</quote> get ignored.
	      Files containing whitespace, a <quote>~</quote>, or a
	      <quote>#</quote> get ignored;
	      Otherwise:
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Every file's (device and) inode gets looked up. All
	      <quote>S</quote> files named the same, but in different
	      <filename>/etc/rc.d/rc?.d</filename> directories must have the
	      same (device and) inode.
	    </para>

	    <para>
	      This verifies that the same <quote>S</quote> file in every
	      <filename>/etc/rc.d/rc?.d</filename> directory is the same
	      script.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The
	      <filename>@INSTALLCONFIGDIR@/system/rc</filename>
	      directory gets created or updated with units that run each
	      script from the <filename>/etc/rc.d/rc?.d</filename>, and
	      the converted units are dependencies of the corresponding
	      <command>vera</command> runlevel target.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      Each unit's starting command runs the <filename>S</filename>
	      script with the <quote>start</quote> parameter.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The existence of a <quote>K</quote> file with the same
	      (device and) inode results in the unit's stopping command
	      getting set, which runs the script with the
	      <quote>stop</quote> parameter. Otherwise there is no explicit
	      stopping command.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      If the <filename>S</filename> or <filename>K</filename> scripts
	      are symbolic links the commands are updated to reflect the
	      symlink target name, as syntactic sugar.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>
	  The <command>rehook</command> command checks that
	  <filename>/sbin/init</filename> is hard-linked to the current
	  <filename>vera-init</filename> executable.
	  Updating (via <command>make install</command> or a built package)
	  installs a new <command>vera-init</command> binary,
	  and this recreates the hard link.
	  <command>rehook</command> then checks all the other files that get
	  hooked via symbolic links. If the symbolic link is gone this is
	  presumed to be the result of erroneously updating the hooked
	  program, and it is re-hooked again using the same process that
	  <command>hook</command> or <command>hookonce</command> uses.
	</para>

	<para>
	  The <command>inittab</command> and
	  <command>rehook</command> commands run automatically when
	  <command>vera</command> gets updated.
	</para>
      </refsect1>

      <refsect1 id="internal">
	<title>Internal commands</title>

	<para>
	  These commands are for internal use only, and are only documented
	  here for completeness.
	</para>

	<para>
	  <quote>sysdown</quote> directs <command>vera</command> on PID 1
	  to set the <envar>RUNLEVEL</envar>
	  environment variable and execute a specified script, replacing
	  PID 1.
	  This is used as a final action for executing a shutdown or a reboot
	  (the <filename>rc.0</filename> and <filename>rc.6</filename>
	  scripts).
	</para>

	<para>
	  The <command>vera-init</command> executable gets linked as
	  <filename>/sbin/init</filename> and it performs a delicate juggling
	  act of switching between <command>vera</command> and the legacy
	  <command>init</command> command, which gets renamed as
	  <filename>/sbin/init.init</filename> by the <quote>hook</quote>
	  command.
	</para>

	<para>
	  When it's not started as PID 1 <command>vera-init</command>
	  determines whether the system was booted by <command>vera</command>
	  or <command>init</command> by connecting to
	  <command>vera</command>'s internal communication socket. A connection
	  failure indicates that <command>vera</command> is hooked as
	  <command>/sbin/init</command> but the system has not been rebooted
	  yet, so <command>vera-init</command> executes
	  <command>/sbin/init.init</command> and forwards all parameters to it.
	  A successful connection indicates that <command>vera</command> is
	  running. <command>vera-init</command> executes
	  the <command>vlad</command> command and forwards its arguments to it.
	</para>

	<para>
	  When started as PID 1 <command>vera-init</command> determines whether
	  the system should be booted by the legacy <command>init</command>
	  or vera.
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      Absence of <command>/sbin/init.init</command> indicates
	      that <command>vera</command> is installed and the legacy
	      <command>init</command> is removed.
	      <command>vera</command> is the only game in town.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>@CONFIGDIR@/hook</filename> is checked, this file
	      is updated by <command>hook</command>,
	      <command>hookonce</command> and <command>unhook</command>
	      commands.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      If <filename>@CONFIGDIR@/hook</filename> exists but its timestamp
	      is identical to <filename>/proc/1</filename>'s timestamp then
	      this is treated as if it does not exist.
	      <command>hook</command>/<command>hookonce</command> intentionally
	      sets the hook file's timestamp like this. <command>init</command>
	      executes itself before a reboot, and this is used to detect this
	      edge case. Even though this is PID 1 the system is not started
	      by <command>vera</command>.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      The absence of <filename>@CONFIGDIR@/hook</filename> results
	      in executing <filename>/sbin/init.init</filename>, the legacy
	      init.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      A <command>hookonce</command> removes
	      <filename>@CONFIGDIR@/hook</filename>, for the next boot.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      At this point a final determination is made that the system
	      is getting booted by <command>vera</command>. Before this happens
	      <command>vera-init</command> reads
	      <filename>/etc/inittab</filename> and directly runs all
	      <command>sysinit</command> commands, then executes
	      <command>vera</command> to start the rest of the system.
	    </para>
	  </listitem>
	</itemizedlist>
      </refsect1>

      <refsect1 id="bugs">
	<title>BUGS</title>

	<para>
	  The <command>vera</command> and
	  <command>vlad</command> commands are not named after any
	  well-known public figures.
	</para>

	<para>
	  <command>vera</command> does not implement
	  <filename>/var/run/runlevel</filename>.
	</para>

	<para>
	  <command>vera</command> does not implement
	  <filename>/dev/initctl</filename>.
	</para>

	<para>
	  Updating <command>sysvinit</command> after hooking into and starting
	  <command>vera</command> results in a mostly bricked system that
	  will not shutdown properly, but will probably reboot into the
	  original <command>init</command> if all filesystems are fully
	  synced before forcing the reboot. Do not update
	  <command>sysvinit</command> before fully
	  unhooking <command>vera</command> (twice) and rebooting back into
	  <command>init</command>
	  (see <xref linkend="management" /> for more information).
	</para>

	<para>
	  Using <command>killall</command> to send a
	  <errorcode>SIGKILL</errorcode> ends up terminating
	  <command>vera</command>'s
	  secondary process that handles commands like
	  <command>status</command>. Use
	  <quote><command>kill -usr1 1</command></quote>
	  to restart it.
	</para>

	<para>
	  <filename>system/rc.M</filename> units always claim they're
	  manually started, even though they get started automatically.
	  This is an artifact of how <command>vera</command>'s
	  <command>inittab</command> command works.
	</para>
      </refsect1>

      <refsect1 id="seealso">
	<title>SEE ALSO</title>

	<para>
	  <link linkend="vera.extras.8">
	    <citerefentry>
              <refentrytitle>vera.extras</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>,
	  <link linkend="vera.logs.8">
	    <citerefentry>
              <refentrytitle>vera.logs</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>,
	  <link linkend="vera.runlevels.8">
	    <citerefentry>
              <refentrytitle>vera.runlevels</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>,
	  <link linkend="vera.units.8">
	    <citerefentry>
              <refentrytitle>vera.units</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>.
	</para>
      </refsect1>

    </refentry>

    <refentry id="vera.runlevels.8">
      <refmeta>
	<refentrytitle>vera runlevels</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo>Double Precision, Inc.</refmiscinfo>
      </refmeta>

      <refnamediv>
	<refname>vera.runlevels</refname>
	<refpurpose>Vera runlevels</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='opt'>--wait</arg>
	  <arg choice='plain'>switch</arg>
	  <arg choice='plain'><replaceable>runlevel</replaceable></arg>
	</cmdsynopsis>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='req'><replaceable>LETTER/DIGIT</replaceable></arg>
	</cmdsynopsis>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='opt'>--override</arg>
	  <arg choice='plain'>default</arg>
	  <arg choice='plain'><replaceable>runlevel</replaceable></arg>
	</cmdsynopsis>
	<cmdsynopsis>
	  <command>vlad</command>
	  <group choice='req'>
	    <arg choice='plain'>current</arg>
	    <arg choice='plain'>default</arg>
	  </group>
	</cmdsynopsis>
      </refsynopsisdiv>
      <refsect1 id="runlevels_description">
	<title>DESCRIPTION</title>
	<para>
	  This manual page is an overview of how
	  <quote>runlevels</quote> are used with
	  <citerefentry>
            <refentrytitle>vera</refentrytitle>
            <manvolnum>8</manvolnum>
	    </citerefentry>.
	</para>

	<para>
	  The term <quote>runlevel</quote> dates back to the original UNIX
	  <command>init</command> process supervisor. At a given time the
	  system is in one of several pre-defined runlevels. The runlevels
	  determine which major system processes are running. The original
	  runlevels were single characters, <command>vera</command> uses
	  more descriptive labels and understands the legacy single-character
	  runlevels as their aliases:
	</para>

	<informaltable>
	  <tgroup cols='3'>
	    <thead>
	      <row>
		<entry><command>vera</command> runlevel</entry>
		<entry><command>init</command> runlevel</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>shutdown</entry><entry>0</entry><entry>System shutdown</entry>
	      </row>
	      <row>
		<entry>single-user</entry><entry>1, S, s</entry><entry>Root login only</entry>
	      </row>
	      <row>
		<entry>networking</entry><entry>2</entry><entry>Custom (same as multi-user), network enabled in some systems</entry>
	      </row>
	      <row>
		<entry>multi-user</entry><entry>3</entry><entry>All logins</entry>
	      </row>
	      <row>
		<entry>graphical</entry><entry>4</entry><entry>Networking and X</entry>
	      </row>
	      <row>
		<entry>custom</entry><entry>5</entry><entry>Unused</entry>
	      </row>
	      <row>
		<entry>reboot</entry><entry>6</entry><entry>reboot</entry>
	      </row>
	    </tbody>
	  </tgroup>
	  <tgroup cols="2">
	    <thead>
	      <row>
		<entry>Additional <command>vera</command> target</entry>
		<entry><filename>inittab</filename> entry</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>system/sigint</entry>
		<entry>ctrlaltdel</entry>
		<entry>Target started in response to <command>vera</command> receiving a <quote>SIGINT</quote> signal</entry>
	      </row>
	      <row>
		<entry>system/powerfail, system/powerfailnow, system/powerok</entry>
		<entry>powerfail, powerfailnow, powerok</entry>
		<entry>Target started in response to <command>vera</command> receiving a <quote>SIGPWR</quote> signal, depending on the contents of <filename>/etc/powerstatus</filename></entry>
	      </row>
	      <row>
		<entry>system/sighup</entry>
		<entry>N/A</entry>
		<entry>Target started in response to <command>vera</command> receiving a <quote>SIGHUP</quote> signal</entry>
	      </row>
	      <row>
		<entry>system/sigwinch</entry>
		<entry>kbrequest</entry>
		<entry>Target started in response to <command>vera</command> receiving a <quote>SIGWINCH</quote> signal</entry>
	      </row>

	      <row>
		<entry>system/a, system/b, and system/c</entry>
		<entry>a, b, and c</entry>
		<entry><quote>On-demand</quote> targets, start by <command>vlad start system/<replaceable>LETTER</replaceable></command></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>
	  The actual behavior and environment of each runlevel depends on
	  how the system is configured. It's also possible to define new
	  runlevels (see <xref linkend="runlevelconfig" /> for more
	  information).
	  The <quote>switch</quote> command takes an argument and changes
	  the system runlevel, for example:
	  <command>vlad switch reboot</command>
	  reboots the system. <command>vera</command> recognizes legacy
	  runlevel aliases, <command>vlad switch 6</command> has the same
	  result.
	</para>

	<para>
	  For compatibility with <command>init</command>,
	  a single parameter to <command>vlad</command> consisting of a
	  single letter or digit gets interpreted as a reference to an
	  <command>init</command> runlevel, an ondemand action, or an
	  inittab update, and triggers the equivalent command.
	  <command>vlad 6</command> also triggers a reboot.
	</para>

	<para>
	  <quote>switch</quote> does not wait for all processes to stop and
	  start and returns immediately. The <quote>--wait</quote> option
	  makes <quote>switch</quote> wait until the switch to the new
	  runlevel finishes.
	</para>

	<para>
	  <quote>current</quote> shows the current <quote>runlevel</quote>.
	  The <quote>default</quote> command shows the default runlevel when
	  the system starts. Passing a parameter to <quote>default</quote>
	  changes the default system startup runlevel.
	</para>

	<note>
	  <para>
	    <command>vlad default <replaceable>runlevel</replaceable></command>
	    sets the default runlevel for the next system boot.
	    <command>vera</command> does not read the default runlevel
	    until it gets started or restarted; but the default runlevel
	    has no other function except to set the runlevel when the system
	    boots.
	  </para>
	</note>

	<para>
	  The <quote>--override</quote> option sets a "temporary"
	  override for the default runlevel.
	  The override gets removed by the next set <quote>default</quote>.
	  The previous default gets restored by setting a default
	  of <quote>default</quote>:
	</para>

	<blockquote>
	  <informalexample>
	    <programlisting>
# vlad default
graphical                 # Current default runlevel is graphical
# vlad default multi-user
# vlad default
multi-user                # New default
# vlad --override default graphical
# vlad default
graphical
# vlad default default
# vlad default
multi-user                # Reverts to the previous default runlevel
	    </programlisting>
	  </informalexample>
	</blockquote>

	<refsect2 id="runlevelconfig">
	  <title>System runlevels</title>

	  <para>
	    The file <filename>@RUNLEVELCONFIG@</filename> defines system
	    runlevels. A default one gets installed and it should only
	    be updated by <command>vlad</command>.
	  </para>

	  <para>
	    This file is a YAML document, a map. The map keys are the
	    canonical names
	    of predefined runlevels. The map values are lists of aliases for
	    each runlevel. Exactly one of the map keys have an alias called
	    <quote>default</quote>, this is the default system runlevel.
	    The <command>vlad default</command> command updates this alias
	    by rewriting the configuration file.
	  </para>

	  <para>
	    <command>vera</command> automatically creates internal
	    units for runlevels' canonical names. Additional unit specification
	    files get installed in
	    <filename>@INSTALLCONFIGDIR@/system</filename>, for each runlevel.
	    These system units,
	    like <quote>system/graphical</quote> and
	    <quote>system/multiuser</quote>,
	    are the ones that's referenced by
	    <quote>enabled</quote> dependencies (see
	    <xref linkend='dependencies' />).
	  </para>
	</refsect2>
      </refsect1>
      <refsect1 id="runlevels_files">
	<title>FILES</title>

	<variablelist>
	  <varlistentry>
	    <term><filename>@RUNLEVELCONFIG@</filename></term>
	    <listitem>
	      <para>
		Runlevel configuration, for compatibility with sysvinit.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
      <refsect1 id="runlevels_seealso">
	<title>SEE ALSO</title>

	<para>
	  <link linkend="vera.8">
	    <citerefentry>
              <refentrytitle>vera</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>.
	</para>
      </refsect1>
    </refentry>

    <refentry id="vera.units.8">
      <refmeta>
	<refentrytitle>vera units</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo>Double Precision, Inc.</refmiscinfo>
      </refmeta>

      <refnamediv>
	<refname>vera.units</refname>
	<refpurpose>Vera units</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='opt'>--nowait</arg>
	  <group choice='req'>
	    <arg choice='plain'>start</arg>
	    <arg choice='plain'>stop</arg>
	    <arg choice='plain'>restart</arg>
	    <arg choice='plain'>reload</arg>
	  </group>
	  <arg choice='plain'><replaceable>unit</replaceable></arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <group choice='req'>
	    <arg choice='plain'>mask</arg>
	    <arg choice='plain'>disable</arg>
	    <arg choice='plain'>enable</arg>
	    <arg choice='plain'>freeze</arg>
	    <arg choice='plain'>thaw</arg>
	  </group>
	  <arg choice='plain'><replaceable>unit</replaceable></arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>setenv</arg>
	  <arg choice='req'><replaceable>name</replaceable></arg>
	  <arg choice='req'><replaceable>value</replaceable></arg>
	</cmdsynopsis>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>unsetenv</arg>
	  <arg choice='req'><replaceable>name</replaceable></arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <group choice='opt'>
	    <arg choice='plain'>--all</arg>
	    <arg choice='plain'>--stopped</arg>
	  </group>
	  <group choice='opt'>
	    <arg choice='plain'>--dependencies</arg>
	    <arg choice='plain'>--resources</arg>
	    <arg choice='plain'>--terse</arg>
	  </group>
	  <arg choice='plain'>status</arg>
	  <arg choice='opt' rep='repeat'>unit</arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>validate</arg>
	  <arg choice='req'>filename</arg>
	  <arg choice='opt'>path</arg>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad</command>
	  <group choice='req'>
	    <arg choice='plain'>edit</arg>
	    <arg choice='plain'>revert</arg>
	  </group>
	  <arg choice='plain'><replaceable>unit</replaceable></arg>
	</cmdsynopsis>
      </refsynopsisdiv>

      <refsect1 id="units_description">
	<title>DESCRIPTION</title>

	<para>
	  The term <quote>unit</quote> refers to each
	  <command>vera</command>-started process
	  (or a collection of processes). Each unit has a unit name, or label,
	  that's used in <command>vera</command>/<command>vlad</command>
	  commands to refer to it.
	  The <quote>start</quote> and <quote>stop</quote> commands start and
	  stop individual units. Units that do not get started automatically
	  (see <link linkend="vera.runlevels.8">
	  <citerefentry>
	    <refentrytitle>vera.runlevels</refentrytitle>
	    <manvolnum>8</manvolnum>
	  </citerefentry>
	  </link>) get started on demand by the
	  <quote>start</quote> command, and <quote>stop</quote> shuts down the
	  unit, irrespective of whether it was started automatically or
	  manually.
	</para>

	<para>
	  Each unit runs in its own control group (a lightweight container),
	  see <citerefentry>
	  <refentrytitle>cgroups</refentrytitle>
	  <manvolnum>7</manvolnum>
	  </citerefentry> for more information.
	</para>

	<para>
	  Running units may or may not have a <quote>restart</quote> or
	  a <quote>reload</quote> capability. <quote>restart</quote> requires the
	  the unit to define its <quote>restart</quote> command.
	  <quote>reload</quote> requires the unit to
	  the define its <quote>reload</quote> command.
	  Only units that are
	  already started can be restarted or reloaded.
	  What a restart or a reload does depends on the unit;
	  generally a restart involves a brief interruption in functionality,
	  but a reload typically maintains functionality while the unit updates
	  itself.
	</para>

	<para>
	  These commands wait until the unit starts, stops, restarts,
	  or reloads. An optional <quote>--nowait</quote> results in
	  the command completing immediately, without waiting for the
	  operation to finish.
	</para>

	<para>
	  Units are either <quote>mask</quote>ed, <quote>disable</quote>d, or
	  <quote>enable</quote>d. These commands change the units'
	  state. A <quote>mask</quote>ed unit never gets started manually
	  or automatically, and <quote>start</quote>ing it fails.
	  Both disabled and enabled units are <quote>start</quote>able.
	  The only difference between a disabled or an enabled unit is that
	  an enabled unit gets automatically started as a result of some
	  other unit starting, typically when the system starts,
	  see <link linkend="vera.runlevels.8">
	  <citerefentry>
	    <refentrytitle>vera.runlevels</refentrytitle>
	    <manvolnum>8</manvolnum>
	  </citerefentry>
	  </link>. Disabled units do not, but
	  they are <quote>start</quote>able directly by themselves, on demand.
	</para>

	<para>
	  Newly installed units are disabled by default.
	</para>

	<note>
	  <para>
	    Not all units define which runlevel they're enabled for.
	    If not, enabling or disabling the unit produces no functional
	    difference.
	  </para>

	  <para>
	    Enabling or disabling a unit may not be related to runlevels,
	    see <xref linkend="dependencies" /> for more information.
	  </para>
	</note>

	<note>
	  <para>
	    The <command>enable</command>, <command>disable</command> and
	    <command>mask</command> commands work differently with
	    units that get created by the <quote>inittab</quote> command
	    (see <xref linkend="management" />) for
	    <filename>/etc/rc.d</filename> scripts.
	    The sysvinit package checks the scripts' permissions and only runs
	    executable scripts.
	  </para>

	  <para>
	    <quote>inittab</quote> creates a
	    <filename>system/rc.M/<replaceable>name</replaceable></filename>
	    unit for these.
	    The <quote>mask</quote> command is disabled for these units.
	    The <quote>enable</quote>
	    and <quote>disable</quote> commands modify the corresponding
	    script's executable permissions.
	  </para>

	  <para>
	    These units are not directly enabled in any particular runlevel.
	    The <filename>/etc/rc.d/rc.M</filename> script checks each
	    script's permissions and (the on-the-fly modified script) starts
	    the corresponding unit if it's executable, and the different
	    behavior of <command>enable</command> and <command>disable</command>
	    ends up having the same result as with regular units.
	  </para>
	</note>

	<para>
	  The <quote>freeze</quote> command pauses all processes in the
	  unit. The processes are not killed or removed, they just stop
	  running. The <quote>thaw</quote> command resumes normal operation
	  of the named unit.
	</para>

	<refsect2 id="envvars">
	  <title>ENVIRONMENT VARIABLES</title>

	  <para>
	    Commands executed by <command>vera</command> (namely the
	    <link linkend="startstop">starting and stopping commands</link>)
	    inherit the following environment variables, in addition to the
	    ones that are set by the <quote>setenv</quote> command (and
	    recorded in <filename>@ENVIRONCONFIG@</filename>).
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term><envar>PATH</envar></term>
	      <listitem>
		<para>
		  The default path is <quote>/usr/local/sbin:/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin</quote>.
		  Any non-default <command>vera</command> installation directory
		  gets prepended to this default path.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><envar>CONSOLE</envar></term>
	      <listitem>
		<para>
		  The path to the system console device in
		  <filename>/dev</filename>.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><envar>INIT_VERSION</envar></term>
	      <listitem>
		<para>
		  <command>vera</command>'s version, for compatibility
		  with <command>init</command>.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><envar>RUNLEVEL</envar> and <envar>PREVRUNLEVEL</envar> (if
	      applicable)</term>
	      <listitem>
		<para>
		  The current and possibly the previous runlevel (the
		  one-character <command>init</command> alias), for
		  compatibility with <command>init</command>.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    The <command>setenv</command> and <command>unsetenv</command>
	    commands update
	    additional environment variables for all commands started
	    by <command>vera</command>. These commands update the
	    <filename>@ENVIRONCONFIG@</filename> file that sets the
	    environment variables for all commands started
	    by <command>vera</command>.
	  </para>
	</refsect2>

	<refsect2 id="status">
	  <title>The <quote>status</quote> command</title>

	  <para>
	    This command shows a list of all units (or just the units given
	    as optional parameters), their current state, and their processes.
	    <quote>status</quote> omits stopped units by default and units
	    that are started but no longer have any processes (targets).
	    The <quote>--all</quote> option includes started units without
	    any processes.
	    <quote>--stopped</quote> option also includes stopped
	    units (so <quote>--all</quote> is not really all of them, the
	    stopped processes are not included).
	    The <quote>--stopped</quote> option is impled if any units are
	    given as parameters.
	  </para>

	  <para>
	    <quote>--dependencies</quote> lists all units' dependencies
	    (which all other units it requires, its required by,
	    and which ones must be started or stopped first, as calculated
	    from the unit's specification, see below).
	    The <quote>--terse</quote> produces a compact status, one container
	    per line, in a parsable format.
	  </para>

	  <para>
	    <quote>--resources</quote> also shows the unit's set resources,
	    see <link linkend="vera.extras.8">
	    <citerefentry>
              <refentrytitle>vera.extras</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link> for more information.
	  </para>

	  <para>
	    <quote>status</quote> reads unit specifications from their
	    directories (see <xref linkend="units" />), the output may be
	    incomplete if the running userid does not have permissions to
	    access them.
	  </para>

	  <informaltable>
	    <tgroup cols='2'>
	      <thead>
		<row>
		  <entry>State</entry>
		  <entry>Description</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry><quote>stopped</quote></entry>
		  <entry>This unit is stopped and is not running</entry>
		</row>
		<row>
		  <entry><quote>start pending</quote> or <quote>start pending (manual)</quote></entry> <entry>This unit is not started yet and it's waiting for other units to be started first, this unit starts after other units get fully started</entry>
		</row>
		<row>
		  <entry><quote>starting</quote> or <quote>starting (manual)</quote></entry>
		  <entry>This unit is starting, but has not finished starting</entry>
		</row>
		<row>
		  <entry><quote>respawning</quote> or <quote>respawning (manual)</quote></entry>
		  <entry>This unit is waiting to be restarted after it failed to start too many times</entry>
		</row>
		<row>
		  <entry><quote>started</quote> or <quote>started (manual)</quote></entry>
		  <entry>This unit is started and is running</entry>
		</row>
		<row>
		  <entry><quote>stop pending</quote></entry>
		  <entry>This unit is waiting for other units to stop, then it'll stop, this unit stops after other units finish stopping</entry>
		</row>
		<row>
		  <entry><quote>stopping</quote></entry>
		  <entry>This unit is in the process of stopping</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>

	  <para>
	    A <quote>manual</quote> annotation indicates that this unit
	    is being started manually, by a <command>vlad start</command>
	    command; otherwise it's started in order to start another unit.
	  </para>

	  <para>
	    The <quote>terse</quote> option shows a subset of the above
	    information and formats the units in a compact list, one unit
	    per line. Each line contains a list of
	    <quote>field=value</quote> tuples, with colons as separators:
	  </para>
	  <blockquote>
	    <informalexample>
	      <programlisting>
# vlad status --terse
name="system/boot":state="started":enabled=0:time=24
name="system/inittab/c1":state="started":enabled=0:time=22:pids="1202 1223 1237 1220"
name="system/inittab/c2":state="started":enabled=0:time=22:pids="1203"
name="system/inittab/c3":state="started":enabled=0:time=22:pids="1204"

# ...</programlisting>
	    </informalexample>
	  </blockquote>
	  <variablelist>
	    <varlistentry>
	      <term><literal>name</literal></term>
	      <listitem>
		<para>
		  The unit's name, quoted.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>state</literal></term>
	      <listitem>
		<para>
		  The unit's state.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>enabled</literal></term>
	      <listitem>
		<para>
		  Whether the unit is marked as enabled.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>elapsed</literal></term>
	      <listitem>
		<para>
		  How long the unit's starting or stopping script is
		  running, in seconds. This is shown only if a starting or
		  a stopping script is currently running.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>time</literal></term>
	      <listitem>
		<para>
		  How long the unit is running, in seconds. This is shown
		  if the unit is in a started state.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>pids</literal></term>
	      <listitem>
		<para>
		  A quoted list of space-delimited process ids in the unit's
		  container, if there are any.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	  <para>
	    This format is amenable to shell scripts:
	  </para>
	  <blockquote>
	    <informalexample>
	      <programlisting>
# eval `vlad status --terse system/inittab/c1 | tr ':' '\012'`
# echo $name
system/inittab/c1
# echo $state
started
echo $pids</programlisting>
	    </informalexample>
	  </blockquote>
	  <note>
	    <para>
	      There's no output from <quote>vlad status</quote> if the given
	      container does not exist or if it's suppressed byx the absense of
	      <option>--all</option> and
	      <option>--stopped</option>. Therefore any
	      existing values of these shell variables remain unchanged.
	    </para>

	    <para>
	      This is also true for variables corresponding to names of
	      values that are not always included in the output (which
	      also includes <quote>pids</quote>!). Caveat emptor.
	    </para>
	  </note>
	</refsect2>
      </refsect1>
      <refsect1 id="units">
	<title>Unit specifications</title>
	<synopsis><filename>@INSTALLCONFIGDIR@</filename></synopsis>
	<synopsis><filename>@LOCALCONFIGDIR@</filename></synopsis>
	<synopsis><filename>@OVERRIDECONFIGDIR@</filename></synopsis>

	<para>
	  Software packages install their unit specification files in
	  <filename>@INSTALLCONFIGDIR@</filename> as described below.
	  <filename>@LOCALCONFIGDIR@</filename> is the local override
	  directory. <command>vera</command> reads a unit file from
	  <filename>@LOCALCONFIGDIR@</filename> if one exists instead of the
	  original one from <filename>@INSTALLCONFIGDIR@</filename>.
	  This allows modifying or adjusting the software package's unit
	  specification file without touching the original one.
	</para>

	<para>
	  <filename>@OVERRIDECONFIGDIR@</filename> gets used for tracking
	  masked and enabled units, and does not normally need any manual
	  intervention.
	</para>

	<note>
	  <para>
	    <command>vera</command> ignores unit specification files in
	    <filename>@LOCALCONFIGDIR@</filename> unless the original
	    one is installed in
	    <filename>@INSTALLCONFIGDIR@</filename>.
	    <filename>@LOCALCONFIGDIR@</filename> overrides, and does not
	    supplement, the contents of
	    <filename>@INSTALLCONFIGDIR@</filename>.
	  </para>

	  <para>
	    These directories get cleaned up when <command>vera</command>
	    starts. Garbled or misnamed
	    unit specification files get removed.
	    Overrides of units
	    that no longer exist in
	    <filename>@INSTALLCONFIGDIR@</filename> also get removed.
	  </para>
	</note>

	<refsect2 id="unitfilename">
	  <title>Filename requirements</title>

	  <para>
	    Names of unit specification files must follow these requirements.
	    The valid
	    characters in unit specification filenames are:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>Lowercase letters <quote>a-z</quote></para>
	    </listitem>
	    <listitem>
	      <para>Uppercase letters <quote>A-Z</quote></para>
	    </listitem>
	    <listitem>
	      <para>Digits <quote>0-9</quote></para>
	    </listitem>
	    <listitem>
	      <para>A space, period, or a dash <quote>-</quote></para>
	    </listitem>
	    <listitem>
	      <para>
		All characters with the high bit set, they are presumed
		to use the default system locale's encoding (but this is not
	      checked)</para>
	    </listitem>
	  </itemizedlist>

	  <para>
	    All other punctuations and characters are prohibited. Additionally:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		A unit specification file's name
		cannot start or end with a space, period, or a dash
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		No two consecutive spaces, periods, or dashes
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Maximum filename length is <quote>NAME_MAX-1</quote> (254
		octets)
	      </para>
	    </listitem>
	  </itemizedlist>

	  <para>
	    Files in the unit specification directories that do not meet these
	    requirements get ignored (and removed during the next reboot).
	  </para>

	  <note>
	    <para>
	      <command>vera</command> reserves unit names prefixed by
	      <quote>system/</quote>
	      for its internal use, specifically.
	    </para>

	    <itemizedlist>
	      <listitem>
		<para>
		  <quote>/</quote> implies that unit specification files
		  can be installed in subdirectories, this is discussed
		  in <xref linkend="hierarchy" />.
		</para>
	      </listitem>

	      <listitem>
		<para>
		  Each runlevel (see
		  <link linkend="vera.runlevels.8">
		    <citerefentry>
		      <refentrytitle>vera.runlevels</refentrytitle>
		      <manvolnum>8</manvolnum>
		    </citerefentry>
		    </link>)
		  has a corresponding
		  <quote>system/<replaceable>name</replaceable></quote>.
		  Installing a unit specification for a specific runlevel
		  is nothing more than defining <quote>enabled:
		  system/<replaceable>name</replaceable></quote> in its
		  specification file, for example:
		</para>
		<blockquote>
		  <informalexample>
		    <literallayout>
enabled:
   - system/multi-user
   - system/graphical&#10;
</literallayout>
		  </informalexample>
		</blockquote>

		<para>
		  Enabling this unit results in it getting started
		  automatically in the <quote>multi-user</quote> and
		  <quote>graphical</quote> runlevels.
		</para>

		<note>
		  <para>
		    Hierarchical and compound units must use absolute
		    dependencies,
		    <quote>/system/multi-user</quote> and
		    <quote>/system/graphical</quote>, for example.
		    (see <xref linkend="dependencies" />
		    for more information).
		  </para>
		</note>
	      </listitem>

	      <listitem>
		<para>
		  Similarly, <quote>system/boot</quote>-required units
		  get started in all runlevels, and before the runlevel-
		  specific units.
		</para>
	      </listitem>
	    </itemizedlist>
	  </note>
	</refsect2>

	<refsect2>
	  <title>Format of unit specification files</title>
	  <para>
	    This section describes the format of unit specification files.
	  </para>
	  <para>
	    The
	    <quote>validate</quote> command reads the
	    <replaceable>filename</replaceable> and checks that it meets
	    all formatting requirements. The command displays the parsed
	    representation of the unit specification. <quote>validate</quote>
	    also reads all existing unit configuration files from
	    <filename>@INSTALLCONFIGDIR@</filename> and prints a warning
	    message if any dependencies in the
	    <replaceable>filename</replaceable> do not exist.
	    This is not an error, <command>vera</command> ignores non-existent
	    dependencies, this is to avoid unintentional typos.
	  </para>

	  <para>
	    <quote>validate</quote> assumes that
	    <replaceable>filename</replaceable> gets installed in
	    <filename>@INSTALLCONFIGDIR@</filename>. If it gets installed in
	    a subdirectory it is necessary to spell out the full subdirectory
	    path, as an optional parameter:
	  </para>
	  <blockquote>
	    <informalexample>
	      <programlisting>
vlad validate startup web/startup
	      </programlisting>
	    </informalexample>
	  </blockquote>
	  <para>
	    This is an example of validating
	    the contents of the <filename>startup</filename> file that
	    gets installed as
	    <filename>@INSTALLCONFIGDIR@/web/startup</filename>.
	  </para>

	  <note>
	    <para>
	      Verifying the validity of dependencies requires that
	      <filename>@INSTALLCONFIGDIR@</filename> and its subdirectories
	      are accessible to the userid that's running
	      <quote>validate</quote>.
	    </para>
	  </note>

	  <para>
	    The <quote>edit</quote> command provides a way to manually edit
	    a unit specification file safely, with error checking.
	    The <quote>edit</quote> command does the following:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		The <quote>edit</quote> command makes a copy of any
		existing modified unit specification file that already
		exists in <filename>@LOCALCONFIGDIR@</filename>, otherwise
		the original unit specification file gets copied from
		<filename>@INSTALLCONFIGDIR@</filename>.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		The copied file gets opened in an editor. The
		<envar>EDITOR</envar> environment variable specifies the
		editor (defaults to
		<command>vi</command>).
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		After the editor terminates (presumably after saving all
		changes to the edited file), the <quote>validate</quote>
		command
		checks the modified unit specification file. If all
		checks pass: the edited file gets installed in
		<filename>@LOCALCONFIGDIR@</filename>, then the
		<quote>edit</quote> command finishes.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Otherwise the <quote>edit</quote> commands offers three
		options after showing all the error messages:
	      </para>
	      <variablelist>
		<varlistentry>
		  <term>Abort</term>
		  <listitem>
		    <para>
		      The <quote>edit</quote> command finishes without
		      making any changes, the temporary copy of the
		      unit specification file gets removed.
		    </para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Re-edit</term>
		  <listitem>
		    <para>
		      The editor runs again, this offers the option to
		      fix the errors, then try to validate it again.
		    </para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>Ignore</term>
		  <listitem>
		    <para>
		      The edited unit specification file gets installed
		      despite the reported errors.
		      This option is available in case the errors come from
		      other unit specification files and not the edited one's
		      (the <quote>validate</quote> command checks all unit
		      specification files that are currently installed).
		    </para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	    </listitem>
	  </itemizedlist>

	  <para>
	    For completeness' sake, the
	    <quote>revert</quote> command deletes the custom
	    unit specification file for the named unit, from
	    <filename>@LOCALCONFIGDIR@</filename>.
	  </para>

	  <para>
	    This is a slightly contrived example of a unit specification file
	    that shows most of its possible settings:
	  </para>

	  <blockquote>
	    <informalexample>
	      <literallayout>
Name: scheduler
Description: "System Scheduler"

Requires-First:
    - boot

Requires:
    - time_service
    - synchronization_service

Required-by:
    - calendar

Enabled:
    - system/multi-user
    - system/graphical

Starting:
    type: forking
    before:
      - conference_service
      - update_service
    after:
      - time_sync
    command: "/usr/bin/scheduler start"

Stopping:
    type: automatic
    after:
      - conference_service
      - update_service
    before:
      - time_sync
    command: "/usr/bin/scheduler stop"

Restart: "/usr/bin/scheduler restart"
Reload: "/usr/bin/scheduler reload"

Version: 1</literallayout>
	    </informalexample>
	  </blockquote>

	  <para>
	    Unit specification files use the <acronym>YAML</acronym> format.
	    This documentation glosses over this detail, and describes the
	    unit specification file format in more general terms.
	  </para>

	  <para>
	    However these are full <acronym>YAML</acronym> documents and can use
	    any logically-equivalent, alternative <acronym>YAML syntax</acronym>.
	    For example:
	  </para>
	  <blockquote>
	    <informalexample>
	      <literallayout>before: [conference_service, update_service]</literallayout>
	    </informalexample>
	  </blockquote>
	  <para>
	    This is a logically equivalent <quote>before</quote> setting
	    from the previous example.
	  </para>

	  <para>
	    A unit specification file is a
	    <quote>Key: value</quote> map. Keys are not case
	    sensitive, <quote>name</quote> and <quote>Name</quote> are equivalent,
	    and there are only two required keys:
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term>name</term>
	      <listitem>
		<para>
		  <quote>name</quote> must be identical to the unit specification
		  file's name.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>version</term>
	      <listitem>
		<para>
		  <quote>version</quote> must be set to 1.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    A <quote>description</quote> is optional.
	    <quote>version</quote> should be the last key in the file. Combined
	    with all other requirements this allows direct installation of
	    unit specification files, without any special procedures.
	    No explicit action is required to notify
	    <command>vera</command> to load them. Unit specification files get
	    ignored unless they have a <quote>version: 1</quote> and their
	    <quote>name</quote> matches their filename. This means that:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		Package management software typically installs packages by
		creating each file with a temporary name, then renaming the
		file after its contents are complete. <command>vera</command>
		ignores anything in <filename>@INSTALLCONFIGDIR@</filename>
		that doesn't parse as valid <acronym>YAML</acronym> and without
		a matching <quote>name</quote>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		Even if a new unit specification file gets copied directly into
		<filename>@INSTALLCONFIGDIR@</filename>, as is: the unit
		specification file gets ignored without a
		<quote>version: 1</quote>. Placing this key at the end of
		unit specification file results in them getting ignored until
		they are complete.
	      </para>
	    </listitem>
	  </itemizedlist>

	  <para>
	    For these reasons there is no <command>vlad</command> command for
	    installing updated
	    <command>vera</command> unit specification files. This
	    happens automatically, with
	    <citerefentry>
              <refentrytitle>inotify</refentrytitle>
              <manvolnum>7</manvolnum>
	      </citerefentry>'s assistance.
	  </para>
	</refsect2>

	<refsect2 id="startstop">
	  <title><quote>Starting</quote> and <quote>Stopping</quote></title>

	  <para>
	    The <quote>Starting</quote> key in a unit specification file contains
	    other <quote>Key: value</quote>
	    pairs that specify how this unit gets started.
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term><quote>command: "/usr/bin/scheduler start"</quote></term>
	      <listitem>
		<para>
		  This key gives the command that starts the unit's programs.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>type: forking</quote></term>
	      <listitem>
		<para>
		  The starting type specifies how the unit gets started.
		  The possible values for <quote>Type</quote> are:
		</para>

		<variablelist>
		  <varlistentry>
		    <term>forking (default)</term>
		    <listitem>
		      <para>
			The starting command forks and its child process
			is the permanent unit process. The original process
			terminates.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term>oneshot</term>
		    <listitem>
		      <para>
			The starting process is the main unit process.
			After the starting process starts running the unit
			is considered to be fully started.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term>respawn</term>
		    <listitem>
		      <para>
			The starting process is the main unit process.
			After the starting process starts running the unit
			is considered to be fully started.
		      </para>

		      <para>
			When the starting process terminates it gets
			immediately restarted.
		      </para>
		    </listitem>
		  </varlistentry>
		</variablelist>

		<note>
		  <para>
		    <quote>respawn</quote> requires a starting command.
		    For other starting types:
		    an unspecified starting command has the same results as if
		    the unit's starting command immediately terminated with
		    an exit code of 0, for a forking unit.
		    A <quote>oneshot</quote>
		    unit without a starting command is effectively a placeholder.
		    The unit is deemed to get started immediately, upon demand,
		    with all the other implications that follow (other units'
		    <quote>before</quote> and <quote>after</quote> dependencies,
		    for example).
		  </para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>timeout: 300</quote></term>
	      <listitem>
		<para>
		  <quote>Timeout</quote> defaults to 60 seconds, if missing.
		  A forking unit's starting command must terminate with a 0
		  exit code before this timeout expires.
		</para>

		<para>
		  Once the forking unit's starting command terminates with a 0
		  exit code the unit is deemed to be started (and other units
		  that start after this get started themselves now).
		</para>

		<para>
		  In all other cases the unit's start is deemed to have failed
		  (see <xref linkend='failedstart' /> below).
		</para>

		<para>
		  A timeout of 0 indicates an infinite timeout, there is no
		  time limit for the starting command.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>before</quote> and <quote>after</quote></term>
	      <listitem>
		<para>
		  These keys specify other units that get started before or
		  after this one (see <xref linkend="dependencies" />).
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    The <quote>Stopping</quote> key in a unit specification file contains
	    other key/value pairs that specify how this unit gets stopped.
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term><quote>command: "/usr/bin/scheduler stop"</quote></term>
	      <listitem>
		<para>
		  This key gives the command that stops the unit's programs..
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>type: manual</quote></term>
	      <listitem>
		<para>
		  The stopping type specifies how the unit gets stopped.
		  The possible values for <quote>Type</quote> are:
		</para>

		<variablelist>
		  <varlistentry>
		    <term>manual (default)</term>
		    <listitem>
		      <para>
			The unit gets stopped by running
			<command>vlad stop</command> for this unit, or if
			another unit that this unit requires gets stopped
			for any reason.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term>automatic</term>
		    <listitem>
		      <para>
			The unit also gets stopped when all of its processes
			stop.
			When the last process in this unit stops this
			has the same
			results as running <command>vlad stop</command>.
		      </para>
		    </listitem>
		  </varlistentry>

		  <varlistentry>
		    <term>target</term>
		    <listitem>
		      <para>
			Only
			<command>vlad stop</command> stops this unit.
			The unit does not get stopped if other units
			required by it are stopped.
		      </para>

		      <para>
			This is used by placeholder units that serve as
			runlevel targets, or as <quote>Required-By</quote>
			or <quote>Enabled</quote> dependencies, for example:
			many units are required by
			<quote>system/multi-user</quote> or other runlevels.
			If any of those units stop this does not stop the
			entire runlevel and all other units in it, even though
			<quote>system/multi-user</quote> formally requires
			them.
		      </para>
		    </listitem>
		  </varlistentry>
		</variablelist>
		<note>
		  <para>
		    It's expected that the stopping command takes appropriate
		    measures to terminate all processes that were previously
		    started. In the event of an automatic stop there won't be any,
		    but the stopping command is free to perform whatever bookkeeping
		    a formal unit stop needs.
		  </para>
		</note>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>timeout: 300</quote></term>
	      <listitem>
		<para>
		  <quote>Timeout</quote> defaults to 60 seconds, if missing.
		  A stopping command must terminate before its timeout expires.
		</para>
		<para>
		  A timeout of 0 indicates an infinite timeout, there is no
		  time limit for the stopping command.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><quote>before</quote> and <quote>after</quote></term>
	      <listitem>
		<para>
		  These keys specify other units that get started before or
		  after this one (see <xref linkend="dependencies" />).
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    After the stopping command times out or terminates any remaining
	    processes in the unit (which may include a stuck stopping command)
	    receive a SIGTERM signal, followed by SIGKILL.
	  </para>

	  <para>
	    Commands inherit the following environment variables:
	  </para>
	  <informaltable>
	    <tgroup cols='2'>
	      <thead>
		<row>
		  <entry>Variable</entry>
		  <entry>Description</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry><envar>RUNLEVEL</envar></entry>
		  <entry>Current
		  <link linkend="vera.runlevels.8">runlevel</link></entry>
		</row>
		<row>
		  <entry><envar>PREVRUNLEVEL</envar></entry>
		  <entry>The previous
		  <link linkend="vera.runlevels.8">runlevel</link></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>

	  <note>
	    <para>
	      <envar>RUNLEVEL</envar> and
	      <envar>PREVRUNLEVEL</envar> are for <command>init</command>
	      compatibility and contain
	      the one digit <command>init</command> runlevel designations
	      (or the full <command>vera</command> runlevel name for a
	      non-default configuration that does not define
	      <command>init</command> aliases).
	    </para>

	    <para>
	      The <quote>switch</quote> command (see
	      <link linkend="vera.runlevels.8">
		<citerefentry>
		  <refentrytitle>vera.runlevels</refentrytitle>
		  <manvolnum>8</manvolnum>
		</citerefentry>
		</link>)
		immediately updates the
		advertized runlevels. Commands started to stop units from the
		previous runlevel see the new runlevel in the
		<envar>RUNLEVEL</envar> environment variable.
	    </para>
	  </note>
	</refsect2>

	<refsect2 id="failedstart">
	  <title>Starting failures</title>

	  <para>
	    An attempt to start a <quote>forking</quote> unit fails if its
	    starting command times out or terminates with a non-zero exit
	    code. This has the following implications:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		Other units that require this unit but are haven't started,
		and are
		waiting for the failed unit to start, do not
		get started any more.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		All same actions that normally happen when the failed unit
		gets stopped also happen, as if the <command>stop</command>
		got executed for this unit, specifically: all other units that
		were started as a failed unit's dependency get now stopped.
	      </para>
	    </listitem>
	  </itemizedlist>
	</refsect2>

	<refsect2 id="reloadrestart">
	  <title><quote>Reload</quote> and <quote>Restart</quote> commands</title>

	  <para>
	    The <quote>reload</quote> key and <quote>restart</quote> keys
	    define the commands executed by <command>vlad reload</command>
	    and <command>vlad restart</command> commands. These commands
	    are allowed only if the unit is already started.
	  </para>
	</refsect2>

	<refsect2 id="respawn">
	  <title><quote>respawn</quote> parameters</title>

	  <para>
	    A <quote>respawn</quote> starting type unit gets restarted
	    up to three times in thirty seconds. This is to prevent a
	    malfunctioning unit from slowing down the system.
	    An optional <quote>respawn</quote> key adjusts these default
	    settings:
	  </para>

	  <blockquote>
	    <informalexample>
	      <literallayout>
Name: sshd
Description: SSH server
Starting:
   Command: /usr/sbin/sshd
   Type: respawn
Respawn:
   attempts: 1
   limit: 60</literallayout>
	    </informalexample>
	  </blockquote>

	  <para>
	    Note that the <quote>type</quote> key in the <quote>starting</quote>
	    section defines this unit as a respawning unit, and the
	    standalone <quote>respawn</quote> key defines the respawning
	    parameters:
	  </para>

	  <variablelist>
	    <varlistentry>
	      <term>attempts</term>
	      <listitem>
		<para>
		  This defines the maximum number of times the unit gets
		  started before it gets limited.
		</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term>limit</term>
	      <listitem>
		<para>
		  This value in the number of seconds before the counter
		  gets reset.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    <command>vera</command> starts this unit at most
	    <replaceable>attempts</replaceable> times in
	    <replaceable>limit</replaceable> seconds. If the unit
	    fails one more time before <replaceable>limit</replaceable>
	    seconds are up, <command>vera</command> waits until
	    <replaceable>limit</replaceable> seconds expire, before attempting
	    to restart the unit again.
	  </para>

	  <note>
	    <para>
	      This is only if when the specified starting command
	      exits normally with a 0 exit status. Any other exit status
	      puts the unit into a penalty box until
	      <replaceable>limit</replaceable> seconds expire before
	      <command>vera</command> restarts the unit again.
	    </para>
	  </note>
	</refsect2>

	<refsect2 id="sigterm">
	  <title><acronym>SIGTERM</acronym> and <acronym>SIGKILL</acronym></title>
	  <para>
	    A unit gets stopped by running its
	    <link linkend="startstop">stopping command</link> if its
	    specified; then
	    sending the <acronym>SIGTERM</acronym> signal to the remaining
	    processes (subject to the settings below),
	    giving them a few seconds to wrap things up on their
	    own, and then immediately <acronym>SIGKILL</acronym>ing any
	    processes that remain.
	  </para>

	  <blockquote>
	    <informalexample>
	      <programlisting>
Name: scheduler
Description: "System Scheduler"
Starting:
    type: forking
    command: "/usr/bin/scheduler start"
Sigterm:
    notify: parents
version: 1
</programlisting>
	    </informalexample>
	  </blockquote>
	  <para>
	    The <quote>Sigterm</quote> key in the unit specification file
	    specifies how processes in the container receive a
	    <acronym>SIGTERM</acronym> signal.
	  </para>
	  <variablelist>
	    <varlistentry>
	      <term>notify: all</term>
	      <listitem>
		<para>
		  All processes in the unit's container get a
		  <acronym>SIGTERM</acronym>.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>notify: parents</term>
	      <listitem>
		<para>
		  Processes that are children of other processes in the same
		  container and which run the same executable as their parent
		  process do not receive a <acronym>SIGTERM</acronym>, only
		  its parent process does. A child process that runs a
		  different executable does get a <acronym>SIGTERM</acronym>
		  normally.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>
	    <quote>notify: parents</quote> is the default if the unit
	    specification file does not have a stopping command.
	    <quote>notify: all</quote> is the default if the unit
	    specification file has an explicit stopping command,
	    <acronym>SIGTERM</acronym> gets sent to all processes after
	    the stopping command finishes.
	  </para>
	</refsect2>
	<refsect2 id="alternativegroups">
	  <title>Alternative Groups</title>

	  <para>
	    An <quote>alternative-group</quote> names units which are not
	    meant to be started at the same time. Starting an
	    <quote>alternative-group</quote> unit automatically stops any
	    other unit in the same <quote>alternative-group</quote>.
	  </para>

	  <blockquote>
	    <informalexample>
	      <literallayout>
Name: http-apache
Description: Apache web server
Alternative-Group: webservers

Version: 1
---
Name: http-nginx
Description: Nginx web server
Alternative-Group: webservers

Version: 1
	      </literallayout>
	    </informalexample>
	  </blockquote>

	  <para>
	    A unit in an alternative group should not have a
	    <quote>Required-By</quote> dependency and other units should not
	    have a <quote>requires</quote> dependency of
	    an alternative group unit
	    (see <xref linkend="dependencies" /> for more information).
	  </para>

	  <para>
	    Names of alternative groups are arbitrary labels that generally
	    follow the same requirements as unit names (but are not unit
	    names and exist in their own namespace):
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		They follow the same requirements as unit filenames and names
		(see <xref linkend="unitfilename" /> for more information).
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		They are resolved according to their unit's hierarchy.
		If the above units are installed as
		<filename>networking/http-apache</filename> and
		<filename>networking/http-nginx</filename> then their
		alternative group's name is really
		<quote>networking/webservers</quote> (unless it's given as
		<quote>/webserver</quote>).
		See <xref linkend="hierarchy" /> for a description of
		unit hierarchies.
	      </para>
	    </listitem>
	  </itemizedlist>
	</refsect2>
      </refsect1>

      <refsect1 id="dependencies">
	<title>Dependencies</title>

	<para>
	  Many settings in unit specification files refer to other units.
	  They describe their mutual relationships and
	  dependencies.
	</para>

	<para>
	  These references are formatted as <acronym>YAML</acronym> lists.
	  A reference to just one other unit can be given as a single
	  scalar value instead of a list with one value.
	</para>

	<para>
	  Other units get referenced by their filename, or
	  <quote>name</quote>. It is not an error if the referenced unit
	  is masked or not installed at all. This gets quietly
	  ignored. The distribution's package manager presumably enforces
	  programs actual dependencies and requirements.
	  <command>vera</command>'s dependencies define mutual relationship
	  between different units when they are installed together:
	</para>

	<variablelist>
	  <varlistentry>
	    <term>The <quote>Requires</quote> dependency</term>
	    <listitem>
	      <para>
		This key is a list of other units
		that get automatically started when this unit gets started.
		A manual or an automatic start of
		this unit also automatically starts the required units.
		Stopping this unit automatically stops the required units if
		they are not required by any other started unit.
	      </para>

	      <para>
		This is a one-way requirement. If unit <command>A</command>
		<quote>Requires: B</quote>, then: starting <command>A</command>
		automatically starts
		<command>B</command> (if it's installed and not masked);
		the opposite is not true.
	      </para>
	      <note>
		<para>
		  <quote>Required</quote> dependencies are transitive.
		  If unit <command>A</command> requires
		  <command>B</command> and
		  <command>B</command> requires
		  <command>C</command>, then
		  <command>A</command> also requires
		  <command>C</command>.
		</para>
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>The <quote>Required-By</quote> dependency</term>
	    <listitem>
	      <para>
		This key is the one-way street in
		the other direction. If unit A is
		<quote>Required-By: B</quote>, then:
		starting <command>B</command> automatically
		starts <command>A</command>; the opposite is not true.
	      </para>

	      <para>
		The <quote>Required-By: B</quote> dependency is logically
		equivalent to <quote>B</quote> specifying a
		<quote>Requires: A</quote>, this has the same result.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>The <quote>Enabled</quote> dependency</term>

	    <listitem>
	      <para>
		This key is equivalent to
		a <quote>required-by</quote>, but takes effect only when the
		unit is enabled.
		It typically refers to runlevels or targets, as described
		above. The only result from a
		<command>vlad enable <replaceable>unit</replaceable></command>
		is that the unit's <quote>enabled</quote> keys get logically
		processed as <quote>required-by</quote>.
	      </para>

	      <para>
		For example: a unit defined that it's
		<quote>enabled: system/graphical</quote>,
		then it gets enabled (by the <command>enable</command> command).
		The resulting
		<quote>required-by</quote>
		of the <quote>system/graphical</quote> has the
		following effect:
		switching, or starting, the
		<quote>system/graphical</quote> runlevel starts this unit
		(as part of the runlevel).
	      </para>

	      <para>
		The order of multiple
		<quote>requires</quote>/<quote>required-by</quote> units is
		immaterial. Listing them in a particular order does not control
		their relative starting or stopping order.
		For example: unit <command>A</command>
		<quote>Requires: [B, C, D, E]</quote>.
		These four units get started by starting <command>A</command>.
		The actual order in
		which they get started gets defined by their
		<quote>before</quote> and <quote>after</quote> dependencies.
		Additionally, a
		<quote>requires-first</quote> dependency (see below) creates
		a <quote>before</quote> and <quote>after</quote> dependencies
		automatically.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>The <quote>Before</quote> and <quote>After</quote>
	    dependencies</term>

	    <listitem>
	      <para>
		These dependencies appear in both the <quote>Starting</quote>
		and <quote>Stopping</quote> keys. They control the
		starting and stopping order when multiple units get started
		or stopped together. When there are two or more units getting
		started or stopped at the same time:
	      </para>

	      <itemizedlist>
		<listitem>
		  <para>
		    <command>vera</command> checks each unit's
		    <quote>Before</quote> and <quote>After</quote> dependencies.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    This uses just the dependencies for the
		    units that are getting started or stopped.
		    Other listed <quote>before</quote>s and <quote>after</quote>s
		    units get ignored.
		  </para>

		  <note>
		    <para>
		      <quote>Before</quote> and <quote>After</quote> dependencies
		      are transitive. For example: <command>A</command> starts
		      before <command>B</command> and <command>B</command>
		      starts before <command>C</command>; <command>D</command>
		      requires <command>A</command> and <command>C</command>.
		      Starting <command>D</command> starts <command>A</command>
		      before <command>C</command>. <command>B</command> does not
		      get started (it's not required by <command>D</command>).
		    </para>
		  </note>
		</listitem>
		<listitem>
		  <para>
		    The <quote>Before</quote> and <quote>After</quote>
		    dependencies get combined to derive their relative starting
		    order, with respect to each other. For example, if
		    <command>A</command> starts <quote>Before: B</quote> then:
		    <command>A</command> gets started before <command>B</command>
		    gets started; if
		    <command>A</command> starts <quote>After: B</quote> then:
		    <command>A</command> gets started after <command>B</command>
		    gets started. The same applies to stopping units.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    A <quote>Requires</quote>/<quote>Required-By</quote>
		    dependency automatically creates the appropriate
		    <quote>Before</quote> and <quote>After</quote> dependencies.
		    A unit <command>A</command> that requires
		    (or requires first, see below)
		    <command>B</command> (directly
		    by it's <quote>Requires</quote> or the other one's
		    <quote>Required-By</quote>) implies that <command>A</command>
		    starts <quote>After</quote> <command>B</command> and
		    stops <quote>Before</quote> <command>B</command>.
		  </para>
		</listitem>

		<listitem>
		  <para>
		    In the absence of direct or indirect ordering between two
		    concurrent units, <command>vera</command> starts or stops
		    them at the same time, in parallel.
		  </para>
		</listitem>

		<listitem>
		  <para>
		    The most common use cases should have mirror images
		    of their starting and stopping dependencies.
		    A <quote>Before</quote> starting dependency is typically
		    a <quote>After</quote> stopping dependency, and vice versa.
		  </para>
		</listitem>

		<listitem>
		  <para>
		    It doesn't take many units to inadvertently create circular
		    dependencies. <command>vera</command> randomly breaks circular
		    dependencies after lodging a complaint.
		  </para>
		</listitem>
	      </itemizedlist>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>The <quote>Requires-First</quote> dependency</term>
	    <listitem>
	      <para>
		A <quote>Requires-First</quote> dependency combines
		<quote>Requires</quote> together with <quote>Before</quote>
		and <quote>After</quote> dependencies.
		A <quote>Requires-First</quote> dependency, first, is
		equivalent to a <quote>Requires</quote> dependency,
		and additionally:
	      </para>

	      <orderedlist>
		<listitem>
		  <para>
		    The transitive set of <quote>Requires</quote> and
		    <quote>Requires-First</quote> dependencies get calculated.
		    For the purposes of this calculation all
		    <quote>Required-By</quote> dependencies are logically
		    the same as specifying the equivalent
		    <quote>Requires</quote> dependencies.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    A second set of transitive dependencies get calculated from
		    <quote>Requires-First</quote> dependencies, only.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    Any units that are present in both sets get removed from
		    the first set. The first set now contains only units that
		    come from <quote>Requires</quote> and
		    <quote>Required-By</quote> depedencnies.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    Every unit in the first set gets a
		    <quote>Starting/After</quote> and a
		    <quote>Stopping/Before</quote> dependency on each
		    <quote>Requires-First</quote> unit.
		  </para>
		</listitem>
	      </orderedlist>

	      <para>
		The end result is that all <quote>Required-First</quote> units
		get started before any of the <quote>Required</quote> units
		(and they get stopped after them). Otherwise,
		<quote>Required-First</quote> and
		<quote>Required</quote> units get started concurrently,
		subject to any other before and after dependencies.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<refsect2 id="hierdep">
	  <title>Specifying hierarchical dependencies</title>

	  <para>
	    A dependency (<quote>Requires</quote>,
	    <quote>Required-By</quote>, and all <quote>Before</quote> and
	    <quote>After</quote>s) can specify a hierarchical name, and
	    it applies to all logical units in that hierarchy.
	  </para>

	  <para>
	    See <xref linkend="hierarchy" /> for a description of
	    unit hierarchies. For example:
	  </para>
	  <blockquote>
	    <informalexample>
	      <programlisting>
Before: networking
	      </programlisting>
	    </informalexample>
	  </blockquote>

	  <para>
	    This defines the dependency for <quote>networking/vpn</quote>,
	    <quote>networking/interfaces</quote> and all other units in the
	    <quote>networking</quote> hierarchy (and to
	    <quote>networking</quote> itself, if this unit is defined).
	  </para>
        </refsect2>
      </refsect1>
      <refsect1 id="additionalconfig">
	<title>ADDITIONAL CONFIGURATION DOCUMENTATION</title>

	<refsect2 id="hierarchy">
	  <title>Hierarchies of unit specification files</title>

	  <para>
	    It's possible to create subdirectories in
	    <filename>@INSTALLCONFIGDIR@</filename> and install
	    unit specification files in the subdirectories. This has
	    several important consequences.
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		The name of each subdirectory must meet the same requirements
		as unit specification filenames (see
		<xref linkend="unitfilename" />) and the maximum filename length
		applies to the entire relative pathname under
		<filename>@INSTALLCONFIGDIR@</filename>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		In the unit specification file: <quote>name</quote> still
		matches the filename (without the subdirectory's name), but
		the unit's logical, or <quote>hierarchical</quote>
		name includes its subdirectory. For example:
		<filename>@INSTALLCONFIGDIR@/networking/vpn</filename>
		unit's logical name is <quote>networking/vpn</quote>; and
		it contains an identifying <quote>name: vpn</quote>.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		<command>vlad</command> commands use hierarchical names.
		<command>vlad start networking/vpn</command> refers to the
		<filename>vpn</filename> unit specification file in
		the <filename>networking</filename> subdirectory.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		Dependency names are "relative" to unit's hierarchical name.
		For example: <filename>networking/vpn</filename> defining
		that it <quote>Requires: interfaces</quote> refers to
		<filename>networking/interfaces</filename>. Its
		<quote>Enabled: ../system/networking</quote> defines that
		it's enabled in the <quote>system/networking</quote> runlevel
		(which can also be defined as
		<quote>Enabled: /system/networking</quote>).
	      </para>
	    </listitem>
	  </itemizedlist>

	  <para>
	    This happens to be how (for example)
	    <quote>Enabled: system/graphical</quote> works in
	    unit specification files that get installed, ordinarily,
	    in <filename>@INSTALLCONFIGDIR@</filename>. It's just a relative
	    pathname.
	  </para>
	</refsect2>
	<refsect2 id="compound">
	  <title>Compound unit specification files</title>

	  <para>
	    It's possible to define multiple unit specification files in
	    a single file, as multiple YAML documents. This is called
	    a compound unit specification file. In plain terms: they're
	    separated by a single line containing three dashes:
	  </para>

	  <blockquote>
	    <informalexample>
	      <programlisting>
name: networking
description: bring up networking
enabled: system/networking
requires:
  - networking/interfaces
  - networking/vpn
starting:
  type: oneshot
stopping:
  type: target
---
name: interfaces
description: enable network interfaces
starting:
  command: /usr/bin/networking start
stopping:
  command: /usr/bin/networking stop
---
name: vpn
description: enable vpns
starting:
  after: interfaces
  command: /usr/bin/vpn start
stopping:
  before: interfaces
  command: /usr/bin/vpn stop

version: 1
	      </programlisting>
	    </informalexample>
	  </blockquote>

	  <para>
	    This hypothetical compound unit specification file is presumed to
	    be installed in
	    <filename>@INSTALLCONFIGDIR@/networking</filename>.
	    Summary of the end results:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>
		The name of the initial YAML section must, as usual
		match its filename, and this sets the hierarchical name
		of unit specification
		file. Its logical name is also what it normally is (if this
		unit specification file gets installed in the
		<filename>local</filename> subdirectory, for example, its
		logical name becomes <quote>local/networking</quote>).
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		All remaining YAML sections in the compound file define
		additional units as if they're installed
		in a subdirectory whose name
		is the name of the unit specification file.
		The above example creates hierarchical names
		<quote>networking/interfaces</quote> and
		<quote>networking/vpn</quote>, in addition to the main
		<quote>networking</quote> one.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		All rules for specifying dependencies use
		unit specification's hierarchical name.
	      </para>
	    </listitem>

	    <listitem>
	      <para>
		The
		<quote>version: 1</quote> requirement still holds. It still
		should be the last key in the physical file. It now logically
		appears as part of the last YAML section, but its only
		purpose is to enforce specification file loading integrity.
		It has no other impact on any specification file's properties.
	      </para>
	    </listitem>
	  </itemizedlist>

	  <note>
	    <para>
	      <command>vlad enable</command>,
	      <command>vlad disable</command> and
	      <command>vlad mask</command> can only be used with the
	      unit specification file's "main" logical name, in this
	      case <quote>networking</quote>. Except for the fact that
	      they're defined in a single, compound file,
	      <filename>networking</filename>,
	      <filename>networking/interfaces</filename> and
	      <filename>networking/vpn</filename> are independent units and,
	      subject to all the usual rules; they can be started or stopped
	      individually. However <command>vlad mask networking</command>
	      logically masks all of them together (same for enabling and
	      disabling where appropriate, see
	      <xref linkend="hierarchy" /> for more information).
	    </para>

	    <para>
	      The alternative approach of using subdirectories allows each
	      individual unit in the subdirectory to be masked, enabled or
	      disabled. On the other hand, using this example, it won't
	      be possible to have a logical <quote>networking</quote> unit,
	      since it's the name of a subdirectory.
	    </para>
	  </note>
	</refsect2>
      </refsect1>
      <refsect1 id="files">
	<title>FILES</title>

	<variablelist>
	  <varlistentry>
	    <term><filename>@INSTALLCONFIGDIR@</filename></term>
	    <listitem>
	      <para>
		Unit specification files.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>@LOCALCONFIGDIR@</filename></term>
	    <listitem>
	      <para>
		Locally-modified unit specification files.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>@OVERRIDECONFIGDIR@</filename></term>
	    <listitem>
	      <para>
		<command>vera</command>-maintained directory that keeps track
		of masked and enabled units.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><filename>@ENVIRONCONFIG@</filename></term>
	    <listitem>
	      <para>
		Environment variables that are set for all started commands.
		This file is maintained by
		<quote>setenv</quote> and <quote>unsetenv</quote>
		commands.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>

      <refsect1 id="units_seealso">
	<title>SEE ALSO</title>

	<para>
	  <link linkend="vera.8">
	    <citerefentry>
              <refentrytitle>vera</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>,
	    <link linkend="vera.runlevels.8">
	      <citerefentry>
		<refentrytitle>vera.runlevels</refentrytitle>
		<manvolnum>8</manvolnum>
	      </citerefentry>
	      </link>.
	</para>
      </refsect1>
    </refentry>

    <refentry id="vera.logs.8">
      <refmeta>
	<refentrytitle>vera logs</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo>Double Precision, Inc.</refmiscinfo>
      </refmeta>

      <refnamediv>
	<refname>vera.logs</refname>
	<refpurpose>Vera logging</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>logs</arg>
	</cmdsynopsis>
	<cmdsynopsis>
	  <command>vlad</command>
	  <arg choice='plain'>log</arg>
	  <arg choice='opt'>number</arg>
	</cmdsynopsis>
      </refsynopsisdiv>

      <refsect1 id="logs_description">
	<title>DESCRIPTION</title>

	<para>
	  <command>vera</command> logs all runlevel switches, this includes
	  system startup and shutdown.
	  The logs are retained for a set number of days, the oldest
	  log files get automatically removed at system startup. The number
	  of days of log
	  retention is controlled by the <envar>SWITCHLOGDAYS</envar>
	  environment variable.
	  <quote><command>vlad setenv SWITCHLOGDAYS 5</command></quote> sets
	  the retention period to five days. At most five days of logs are
	  kept (dates without logs don't count toward the limit).
	</para>

	<note>
	  <para>
	    There will be an extra day of logs at times. Logs get purged
	    at system boot before a new log gets created, possibly for a brand
	    new day.
	  </para>
	</note>

	<blockquote>
	  <informalexample>
	    <programlisting><![CDATA[
       # vlad logs
       2 2024-03-23 20:52:48 reboot
       1 2024-03-23 20:53:18 multi-user]]></programlisting>
	  </informalexample>
	</blockquote>

	<para>
	  The <command>logs</command> commands lists all available switch
	  logs, from the oldest to the newest. It produces the following
	  output:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      The log number. The logs are numbered from
	      the newest to the oldest, so log #1 is always the most recent
	      log.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The timestamp of each runlevel switch.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      Which runlevel was switched to.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>
	  The log files record low-level details and times, the
	  <quote><command>vlag log</command></quote>
	  command reads log file #1, the
	  most recent log file,
	  and processes the logs into a basic list of units and how
	  long it took for each unit to start.
	  An optional parameter reads a different log file.
	  <quote><command>vlag log 2</command></quote> reads log file #2.
	</para>

	<para>
	  The <command>log</command> command produces a listing of units
	  that were started or stopped, one units per line.
	  Each line contains:
	</para>

	<itemizedlist>
	  <listitem>
	    <para>
	      How long the unit's starting or stopping command took to ran
	      to completion.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      How long the unit waited for other units to start
	      or stop, before it could start or stop.
	    </para>
	  </listitem>

	  <listitem>
	    <para>
	      The unit's name.
	    </para>
	  </listitem>
	</itemizedlist>

	<para>
	  An asterisk, <quote>*</quote> appears at the beginning of the line
	  of the unit that took the longest time to start or stop.
	  The asterisk's only purpose is to identify the unit with the
	  longest starting or stopping time.
	</para>
      </refsect1>
      <refsect1 id="logs_seealso">
	<title>SEE ALSO</title>

	<para>
	  <link linkend="vera.8">
	    <citerefentry>
              <refentrytitle>vera</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>.
	</para>
      </refsect1>

      <refsect1 id="logs_bugs">
	<title>BUGS</title>

	<para>
	  <literal>system/inittab/rc</literal> often gets fingered as the
	  slowest-starting unit. The actual culprit will be some other
	  unit that gets started by <literal>system/inittab/rc</literal>.
	  This is an artifact of how the <quote>inittab</quote> command
	  converts the <command>init</command>scripts to
	  <command>vera</command> units.
	</para>
      </refsect1>
    </refentry>

    <refentry id="vera.extras.8">
      <refmeta>
	<refentrytitle>vera extras</refentrytitle>
	<manvolnum>8</manvolnum>
	<refmiscinfo>Double Precision, Inc.</refmiscinfo>
      </refmeta>

      <refnamediv>
	<refname>vera.extras</refname>
	<refpurpose>Optional vera features</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<cmdsynopsis>
	  <command>vlad enable system/networkmanager-wait-online</command>
	</cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad enable system/v2-controllers</command>
	</cmdsynopsis>

	  <cmdsynopsis>
	    <command>vlad set-resource <replaceable>unit</replaceable> <replaceable>resource</replaceable> <replaceable>value</replaceable></command>
	  </cmdsynopsis>

	  <cmdsynopsis>
	    <command>vlad delete-resource <replaceable>unit</replaceable> <replaceable>resource</replaceable></command>
	  </cmdsynopsis>

	<cmdsynopsis>
	  <command>vlad restart system/rc.M/rc.<replaceable>name</replaceable></command>
	</cmdsynopsis>
      </refsynopsisdiv>

      <refsect1 id="extras_description">
	<title>DESCRIPTION</title>

	<para>
	  This manual page describes additional <command>vera</command>
	  features.
	</para>

	<refsect2 id="networkmanager-wait-online">
	  <title><quote>system/network-online</quote> and
	  <quote>system/networkmanager-wait-online</quote></title>

	  <para>
	    The <command>inittab</command> command adds a
	    requirement on the <quote>system/network-online</quote>
	    target to every converted <filename>/etc/rc.d/rc.inet2</filename>
	    unit.
	  </para>

	  <para>
	    The installed <quote>system/networkmanager-wait-online</quote> unit
	    can be enabled, this unit gets enabled for
	    <quote>system/network-online</quote>.
	    This unit runs <command>/usr/bin/nm-online</command>
	    when started.
	  </para>

	  <para>
	    If a system uses <filename>/etc/rc.d/rc.networkmanager</filename>
	    then enabling <quote>system/networkmanager-wait-online</quote>
	    delays system startup until NetworkManager initializes all
	    network interfaces (all network interfaces come up with an
	    active IP address). <quote>system/networkmanager-wait-online</quote>
	    should not be enabled unless
	    <quote>system/rc.M/rc.networkmanager</quote> is also enabled.
	  </para>
	</refsect2>

	<refsect2 id="v2-controllers">
	  <title>Enabling cgroup v2 controllers and setting resources</title>

	  <para>
	    Slackware's default <filename>/etc/rc.d/rc.S</filename> script
	    mounts all cgroup version 1 controllers in
	    <filename>/sys/fs/cgroup</filename>.
	  </para>

	  <para>
	    Enabling the <quote>system/v2-controllers</quote> unit
	    runs a script at system boot that enables cgroup version 2
	    controllers after shutting down the
	    cgroup version 1 controllers. This makes controllers
	    available to cgroup version 2 containers. The cgroup
	    version 2 controllers get enabled
	    for <command>vera</command>'s units.
	  </para>

	  <para>
	    If version 1 controllers are turned off via a kernel boot
	    parameter, the cgroup version 2 controllers are still enabled
	    for <command>vera</command>'s units.
	  </para>

	  <para>
	    With enabled version 2 controllers it is possible to set
	    controller-managed resources using the <quote>set-resource</quote>
	    command.
	  </para>

	  <para>
	    The <quote>set-resource</quote> command sets the given
	    <replaceable>unit</replaceable>'s
	    <replaceable>resource</replaceable> to a
	    <replaceable>value</replaceable>, example:
	  </para>

	  <para>
	    <command>vlad set-resource system/rc.M/rc.sshd pids.max 100</command>
	  </para>

	  <para>
	    This limits <quote>system/rc.M/rc.sshd</quote> to 100
	    processes .
	    The <quote>delete-resource</quote> command removes the
	    <replaceable>unit</replaceable>'s
	    <replaceable>resource</replaceable>, reverting it to the
	    Linux kernel's default.
	  </para>

	  <para>
	    The resources actually get set when a unit starts. The
	    <quote>set-resource</quote> and <quote>delete-resource</quote>
	    commands update the saved list of resources for each unit, and
	    they take effect when the unit starts. If the unit is already
	    running the new resources take effect the next time the unit
	    starts.
	  </para>

	  <para>
	    See the <ulink url="https://docs.kernel.org/admin-guide/cgroup-v2.html#controllers">Linux kernel's control group V2 documentation</ulink>
	    for a list of settable resources.
	  </para>

	  <refsect3>
	    <title>Advanced resource control</title>
	    <para>
	      The <quote>set-resource</quote> command implements a generic
	      interface to control group resources.
	      <command>vlad</command> does not have any specific knowledge
	      of any specific resource and what it does.
	      <quote>set-resource</quote> does a sanity check that only
	      verifies that the specified resource interface file exists, and
	      accepts any <replaceable>value</replaceable>.
	      When a unit starts the each resource is set to its value, one by
	      one.
	    </para>

	    <para>
	      Each resource is set by opening the interface file, of the same
	      name, as described
	      in the Linux kernel's documentation, and writing the given
	      <replaceable>value</replaceable> to it. Note that not every
	      interface file described in the kernel's documentation is
	      settable.
	    </para>

	    <para>
	      <quote>set-resource</quote> takes multiple values.
	      Multiple values get written to the interface file one at a time.
	      Whether or not this has any effect is up to the controller,
	      otherwise the last value becomes the effective one.
	      If a resource value, or values are already set,
	      <quote>set-resource</quote> replaces the values.
	      There's also an <quote>add-resource</quote> command that sets
	      additional values without removing any existing ones.
	    </para>

	    <para>
	      A newly-created container's resources get set
	      in the <quote>set-resource</quote>d order. The
	      <command>status</command> command with the
	      <option>--resources</option> option lists a unit's resources
	      in the order they were set.
	    </para>
	  </refsect3>
	  <refsect3>
	    <title>Summary of common resources</title>

	    <para>
	      This is a summary of most common resources from the Linux
	      kernel documentation. Consult the kernel's documentation for
	      more information.
	    </para>

	    <variablelist>
	      <varlistentry>
		<term>cpu.idle</term>
		<listitem>
		  <para>
		    Setting <quote>cpu.idle</quote> to 1 schedules this
		    unit at a lowest possible priority.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>memory.max</term>
		<listitem>
		  <para>
		    <quote>memory.max</quote> is the maximum memory used
		    by the unit, in bytes.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>memory.oom.group</term>
		<listitem>
		  <para>
		    Setting <quote>memory.oom.group</quote> to 1 results
		    in all processes in the unit getting killed by the OOM
		    killer, instead of individual processes.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>pids.max</term>
		<listitem>
		  <para>
		    <quote>pids.max</quote> sets an upper limit on the
		    number of processes that can be created in the unit.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </refsect3>
	</refsect2>

	<refsect2 id="rc-restart-and-reload">
	  <title><command>restart</command> and <command>reload</command>
	  commands for <filename>/etc/rc.d</filename> units</title>

	  <para>
	    The <command>inittab</command> command installs a unit for every
	    script in <filename>/etc/rc.d</filename> that gets started from
	    <filename>/etc/rc.d/rc.M</filename> and
	    <filename>/etc/rc.d/rc.inet2</filename>. Each unit is named
	    <filename>system/rc.M/<replaceable>name</replaceable></filename>.
	  </para>

	  <para>
	    Each <filename>/etc/rc.d</filename> script is scanned and
	    heuristically determined if it implements a
	    <quote>restart</quote> and/or a <quote>reload</quote> operation.
	    If so, then a <quote>restart</quote> and/or a <quote>reload</quote>
	    command gets included in the corresponding unit specification
	    file.
	  </para>

	  <para>
	    For example: <quote>vlad restart system/rc.M/rc.sshd</quote>
	    executes <command>/etc/rc.d/rc.sshd restart</command> in this
	    unit's container.
	  </para>
	</refsect2>
      </refsect1>
      <refsect1 id="extras_files">
	<title>FILES</title>

	<variablelist>
	  <varlistentry>
	    <term><filename>@CONFIGDIR@/cgroup.controllers</filename></term>

	    <listitem>
	      <para>
		This configuration file lists which group version 2 controllers
		get enabled, for <command>vera</command>, by the
		<quote>system/v2-controllers</quote> unit.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
      <refsect1 id="extras_seealso">
	<title>SEE ALSO</title>

	<para>
	  <link linkend="vera.units.8">
	    <citerefentry>
              <refentrytitle>vera.units</refentrytitle>
              <manvolnum>8</manvolnum>
	    </citerefentry>
	    </link>.
	</para>
      </refsect1>
    </refentry>
  </sect1>
</article>