Add a section to the handbook to mention portsnap.
Reviewed by: simon, pav Approved by: simon
This commit is contained in:
Colin Percival
parent
73c9ea236e
commit
e37c0a6ebf
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=26206
2 changed files with 159 additions and 0 deletions
|
|
@ -2333,6 +2333,164 @@ doc/zh_*</screen>
|
|||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="portsnap">
|
||||
<title>Using portsnap</title>
|
||||
|
||||
<sect2 id="portsnap-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para><application>Portsnap</application> is a system for securely
|
||||
distributing the &os; ports tree. Approximately once an hour,
|
||||
a <quote>snapshot</quote> of the ports tree is generated,
|
||||
repackaged, and cryptographically signed. The resulting files
|
||||
are then distributed via HTTP.</para>
|
||||
|
||||
<para>Like <application>CVSup</application>,
|
||||
<application>portsnap</application> uses a
|
||||
<emphasis>pull</emphasis> model of updating: The packaged and
|
||||
signed ports trees are placed on a web server which waits
|
||||
passively for clients to request files. Users must either run
|
||||
<application>portsnap</application> manually to download updates
|
||||
or set up a <command>cron</command> job to download updates
|
||||
automatically on a regular basis.</para>
|
||||
|
||||
<para>For technical reasons, <application>portsnap</application>
|
||||
does not update the <quote>live</quote> ports tree in
|
||||
<filename>/usr/ports/</filename> directly; instead, it works
|
||||
via a compressed copy of the ports tree stored in
|
||||
<filename>/var/db/portsnap/</filename> by default. This
|
||||
compressed copy is then used to update the live ports tree.</para>
|
||||
|
||||
<note>
|
||||
<para>If <application>portsnap</application> is installed from
|
||||
the &os; Ports Collection, then the default location for its
|
||||
compressed snapshot will be <filename>/usr/local/portsnap/</filename>
|
||||
instead of <filename>/var/db/portsnap/</filename>.</para>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="portsnap-install">
|
||||
<title>Installation</title>
|
||||
|
||||
<para>On &os; 6.0 and more recent versions,
|
||||
<application>portsnap</application> is contained in the &os;
|
||||
base system. On older versions of &os;, it can be installed
|
||||
using the <filename role="package">sysutils/portsnap</filename>
|
||||
port.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="portsnap-config">
|
||||
<title>Portsnap Configuration</title>
|
||||
|
||||
<para><application>Portsnap</application>'s operation is controlled
|
||||
by the <filename>/etc/portsnap.conf</filename> configuration
|
||||
file. For most users, the default configuration file will
|
||||
suffice; for more details, consult the &man.portsnap.conf.5;
|
||||
manual page.</para>
|
||||
|
||||
<note>
|
||||
<para>If <application>portsnap</application> is installed from
|
||||
the &os; Ports Collection, it will use the configuration file
|
||||
<filename>/usr/local/etc/portsnap.conf</filename> instead of
|
||||
<filename>/etc/portsnap.conf</filename>. This configuration
|
||||
file is not created when the port is installed, but a sample
|
||||
configuration file is distributed; to copy it into place, run
|
||||
the following command:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/local/etc && cp portsnap.conf.sample portsnap.conf</userinput></screen>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Running <application>Portsnap</application> for the first
|
||||
time</title>
|
||||
|
||||
<para>The first time <application>portsnap</application> is run,
|
||||
it will need to download a compressed snapshot of the entire
|
||||
ports tree into <filename>/var/db/portsnap/</filename> (or
|
||||
<filename>/usr/local/portsnap/</filename> if
|
||||
<application>portsnap</application> was installed from the
|
||||
Ports Collection). This is approximately a 36 MB
|
||||
download.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
|
||||
|
||||
<para>Once the compressed snapshot has been downloaded, a
|
||||
<quote>live</quote> copy of the ports tree can be extracted into
|
||||
<filename>/usr/ports/</filename>. This is necessary even if a
|
||||
ports tree has already been created in that directory (e.g., by
|
||||
using <application>CVSup</application>), since it establishes a
|
||||
baseline from which <application>portsnap</application> can
|
||||
determine which parts of the ports tree need to be updated
|
||||
later.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Updating the ports tree</title>
|
||||
|
||||
<para>After an initial compressed snapshot of the ports tree has
|
||||
been downloaded and extracted into <filename>/usr/ports/</filename>,
|
||||
updating the ports tree consists of two steps:
|
||||
<emphasis>fetch</emphasis>ing updates to the compressed
|
||||
snapshot, and using them to <emphasis>update</emphasis> the
|
||||
live ports tree. These two steps can be specified to
|
||||
<application>portsnap</application> as a single command.</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
|
||||
|
||||
<note>
|
||||
<para>Some older versions of <application>portsnap</application>
|
||||
do not support this syntax; if it fails, try instead the
|
||||
following:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>portsnap fetch</userinput>
|
||||
&prompt.root; <userinput>portsnap update</userinput></screen>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Running portsnap from cron</title>
|
||||
|
||||
<para>In order to avoid problems with <quote>flash crowds</quote>
|
||||
accessing the <application>portsnap</application> servers,
|
||||
<userinput>portsnap fetch</userinput> will not run from
|
||||
a <command>cron</command> job. Instead, a special
|
||||
<userinput>portsnap cron</userinput> command exists, which
|
||||
waits for a random duration up to 3600 seconds before fetching
|
||||
updates.</para>
|
||||
|
||||
<para>In addition, it is strongly recommended that
|
||||
<userinput>portsnap update</userinput> not be run from a
|
||||
<command>cron</command> job, since it is liable to cause
|
||||
major problems if it happens to run at the same time as a port
|
||||
is being built or installed. However, it is safe to update
|
||||
the ports INDEX files, and this can be done by passing the
|
||||
<option>-I</option> flag to
|
||||
<application>portsnap</application>. (Obviously, if
|
||||
<command>portsnap -I update</command> is run from
|
||||
<command>cron</command>, then it will be necessary to run
|
||||
<command>portsnap update</command> without the <option>-I</option>
|
||||
flag at a later time in order to update the rest of the tree.)</para>
|
||||
|
||||
<para>Adding the following line to <filename>/etc/crontab</filename>
|
||||
will cause <application>portsnap</application> to update its
|
||||
compressed snapshot and the INDEX files in
|
||||
<filename>/usr/ports/</filename>, and will send an email if any
|
||||
installed ports are out of date:</para>
|
||||
|
||||
<screen>0 3 * * * root portsnap -I cron update && pkg_version -vIL=</screen>
|
||||
|
||||
<note>
|
||||
<para>If the system clock is not set to the local time zone,
|
||||
please replace <userinput>3</userinput> with a random
|
||||
value between 0 and 23, in order to spread the load on the
|
||||
<application>portsnap</application> servers more evenly.</para>
|
||||
</note>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="cvs-tags">
|
||||
<title>CVS Tags</title>
|
||||
|
||||
|
|
|
|||
|
|
@ -3800,6 +3800,7 @@
|
|||
<!ENTITY man.phones.5 "<citerefentry/<refentrytitle/phones/<manvolnum/5//">
|
||||
<!ENTITY man.pim6dd.conf.5 "<citerefentry/<refentrytitle/pim6dd.conf/<manvolnum/5//">
|
||||
<!ENTITY man.pim6sd.conf.5 "<citerefentry/<refentrytitle/pim6sd.conf/<manvolnum/5//">
|
||||
<!ENTITY man.portsnap.conf.5 "<citerefentry/<refentrytitle/portsnap.conf/<manvolnum/5//">
|
||||
<!ENTITY man.printcap.5 "<citerefentry/<refentrytitle/printcap/<manvolnum/5//">
|
||||
<!ENTITY man.procfs.5 "<citerefentry/<refentrytitle/procfs/<manvolnum/5//">
|
||||
<!ENTITY man.procmailex.5 "<citerefentry vendor='ports'/<refentrytitle/procmailex/<manvolnum/5//">
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue