openafs/doc/xml/AdminReference/sect8/bos_install.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="bos_install8">
  <refmeta>
    <refentrytitle>bos install</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>bos install</refname>
    <refpurpose>Installs a new version of a binary file</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Synopsis</title>
    <para><emphasis role="bold">bos install</emphasis> <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-file</emphasis> &lt;<emphasis>files to install</emphasis>&gt;+
        [<emphasis role="bold">-dir</emphasis> &lt;<emphasis>destination dir</emphasis>&gt;] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
        [<emphasis role="bold">-noauth</emphasis>] [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>

    <para><emphasis role="bold">bos i</emphasis> <emphasis role="bold">-s</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-f</emphasis> &lt;<emphasis>files to install</emphasis>&gt;+
        [<emphasis role="bold">-d</emphasis> &lt;<emphasis>destination dir</emphasis>&gt;] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-n</emphasis>]
        [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>

  </refsect1>
  <refsect1>
    <title>Description</title>
    <para>The <emphasis role="bold">bos install</emphasis> command copies each binary file specified with the
    <emphasis role="bold">-file</emphasis> argument to the local disk of the server machine named by the
    <emphasis role="bold">-server</emphasis> argument, which is normally the binary distribution machine for
    its CPU/operating system type. The destination directory is
    <replaceable>/usr/afs/bin</replaceable> unless the <emphasis role="bold">-dir</emphasis> argument indicates an alternate
    directory. The source file's UNIX mode bits are preserved in the transfer.</para>

    <para>If there is already a file of the same name in the destination directory,
    the BOS Server automatically saves it by adding a <computeroutput>.BAK</computeroutput> extension. If
    there is a current <computeroutput>.BAK</computeroutput> version at least seven days old, it replaces
    the current <computeroutput>.OLD</computeroutput> version. If there is no current <computeroutput>.OLD</computeroutput> version, the
    current <computeroutput>.BAK</computeroutput> version becomes the <computeroutput>.OLD</computeroutput> version automatically. The
    <emphasis role="bold">bos getdate</emphasis> command displays the timestamps on the current versions of
    the file.</para>

    <para>To start using the new binary immediately, issue the bos restart
    command. Otherwise, the BOS Server automatically restarts the process at
    the time defined in the <replaceable>/usr/afs/local/BosConfig</replaceable> file; use the <emphasis role="bold">bos
    getrestart</emphasis> command to display the time and the <emphasis role="bold">bos setrestart</emphasis> time to
    set it.</para>

  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
        <listitem>
          <para>Indicates the binary distribution machine on which to install the new
          binaries. Identify the machine by IP address or its host name (either
          fully-qualified or abbreviated unambiguously). For details, see <link linkend="bos8">bos(8)</link>.</para>

          <para>If the machine is not a binary distribution machine and is running an
          <computeroutput>upclientbin</computeroutput> process, then the files are overwritten the next time the
          <computeroutput>upclientbin</computeroutput> process fetches the corresponding file from the
          distribution machine (by default within five minutes).</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-file</emphasis> &lt;<emphasis>files to install</emphasis>&gt;+</term>
        <listitem>
          <para>Specifies the complete pathname of each binary file to copy into the
          destination directory. Each source directory can be on the local disk or
          in AFS, in which case the issuer of the <emphasis role="bold">bos install</emphasis> command must have
          the necessary AFS access rights and the local machine must run the Cache
          Manager. For the BOS Server to create <computeroutput>.BAK</computeroutput> and <computeroutput>.OLD</computeroutput> versions, the
          last element in the pathname (the filename) must match the name of a file
          in the destination directory.  <link linkend="bos_create8">bos_create(8)</link> lists the standard binary
          file names.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-dir</emphasis> &lt;<emphasis>destination dir</emphasis>&gt;</term>
        <listitem>
          <para>Provides the complete pathname of the local disk directory in which to
          install binary files. It is necessary only if the destination directory
          is not <replaceable>/usr/afs/bin</replaceable>.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
        <listitem>
          <para>Names the cell in which to run the command. Do not combine this argument
          with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="bos8">bos(8)</link>.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-noauth</emphasis></term>
        <listitem>
          <para>Assigns the unprivileged identity <computeroutput>anonymous</computeroutput> to the issuer. Do not
          combine this flag with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see
          <link linkend="bos8">bos(8)</link>.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-localauth</emphasis></term>
        <listitem>
          <para>Constructs a server ticket using a key from the local
          <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">bos</emphasis> command interpreter presents the
          ticket to the BOS Server during mutual authentication. Do not combine this
          flag with the <emphasis role="bold">-cell</emphasis> or <emphasis role="bold">-noauth</emphasis> options. For more details, see
          <link linkend="bos8">bos(8)</link>.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-help</emphasis></term>
        <listitem>
          <para>Prints the online help for this command. All other valid options are
          ignored.</para>

        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Examples</title>
    <para>The following command copies the file
    <replaceable>/afs/abc.com/rs_aix42/usr/afs/bin/vlserver</replaceable> to the file
    <replaceable>/usr/afs/bin/vlserver</replaceable> on the machine <computeroutput>fs3.abc.com</computeroutput>, which is the
    binary distribution machine for server machines running AIX 4.2 in the
    <computeroutput>abc.com</computeroutput> cell. The current version of the <replaceable>/usr/afs/bin/vlserver</replaceable> file
    is moved to <replaceable>/usr/afs/bin/vlserver.BAK</replaceable>.</para>

<programlisting>
   % bos install -server fs3.abc.com \
                 -file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver

</programlisting>
    </refsect1>
    <refsect1>
      <title>Privilege Required</title>
      <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on the
      machine named by the <emphasis role="bold">-server</emphasis> argument, or must be logged onto a server
      machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
      included.</para>

    </refsect1>
    <refsect1>
      <title>See Also</title>
      <para><link linkend="BosConfig5">BosConfig(5)</link>,
      <link linkend="KeyFile5">KeyFile(5)</link>,
      <link linkend="UserList5">UserList(5)</link>,
      <link linkend="bos8">bos(8)</link>,
      <link linkend="bos_getdate8">bos_getdate(8)</link>,
      <link linkend="bos_getrestart8">bos_getrestart(8)</link>,
      <link linkend="bos_restart8">bos_restart(8)</link>,
      <link linkend="bos_setrestart8">bos_setrestart(8)</link></para>

    </refsect1>
    <refsect1>
      <title>Copyright</title>
      <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>

      <para>This documentation is covered by the IBM Public License Version 1.0.  It was
      converted from HTML to POD by software written by Chas Williams and Russ
      Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>

    </refsect1>
  </refentry>