usr.sbin/portsnap/portsnap/portsnap.8

   1 .\"-
   2 .\" Copyright 2004-2005 Colin Percival
   3 .\" All rights reserved
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted providing that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  16 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  18 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  22 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  23 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 15, 2008
  29 .Dt PORTSNAP 8
  30 .Os FreeBSD
  31 .Sh NAME
  32 .Nm portsnap
  33 .Nd fetch and extract compressed snapshots of the ports tree
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl I
  37 .Op Fl d Ar workdir
  38 .Op Fl f Ar conffile
  39 .Op Fl k Ar KEY
  40 .Op Fl l Ar descfile
  41 .Op Fl p Ar portsdir
  42 .Op Fl s Ar server
  43 .Cm command ...
  44 .Op Ar path
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 tool is used to fetch and update compressed snapshots
  49 of the
  50 .Fx
  51 ports tree, and extract and update an
  52 uncompressed ports tree.
  53 .Sh OPTIONS
  54 The following options are supported:
  55 .Bl -tag -width "-f conffile"
  56 .It Fl d Ar workdir
  57 Store working files (e.g.\& downloaded updates) in
  58 .Ar workdir .
  59 (default:
  60 .Pa /var/db/portsnap ,
  61 or as given in the configuration file.)
  62 .It Fl f Ar conffile
  63 Read the configuration from
  64 .Ar conffile .
  65 (default:
  66 .Pa /etc/portsnap.conf )
  67 .It Fl I
  68 For the
  69 .Cm update
  70 command, update INDEX files, but not the rest of the ports tree.
  71 .It Fl k Ar KEY
  72 Expect a public key with given SHA256 hash.
  73 (default: read value from configuration file.)
  74 .It Fl l Ar descfile
  75 Merge the specified local describes file into the INDEX files being
  76 built.
  77 The
  78 .Ar descfile
  79 should be generated by running
  80 .Cm make describe
  81 in each of the local port directories.
  82 .It Fl p Ar portsdir
  83 When extracting or updating an uncompressed snapshot,
  84 operate on the directory
  85 .Ar portsdir .
  86 (default:
  87 .Pa /usr/ports/ ,
  88 or as given in the configuration file.)
  89 .It Fl s Ar server
  90 Fetch files from the specified server or server pool.
  91 (default: portsnap.FreeBSD.org , or as given in the
  92 configuration file.)
  93 .It path
  94 For
  95 .Cm extract
  96 command only, operate only on parts of the ports tree starting with
  97 .Ar path .
  98 (e.g.\&
  99 .Nm
 100 .Cm extract
 101 .Ar sysutils/port
 102 would extract sysutils/portsman, sysutils/portsnap,
 103 sysutils/portupgrade, etc.)
 104 .El
 105 .Sh COMMANDS
 106 The
 107 .Cm command
 108 can be any one of the following:
 109 .Pp
 110 .Bl -tag -width "-f conffile"
 111 .It fetch
 112 Fetch a compressed snapshot of the ports tree, or update
 113 the existing snapshot.
 114 This command should only be used interactively; for
 115 non-interactive use, you should use the
 116 .Cm cron
 117 command.
 118 .It cron
 119 Sleep a random amount of time between 1 and 3600 seconds,
 120 then operate as if the
 121 .Cm fetch
 122 command was specified.
 123 As the name suggests, this command is designed for running
 124 from
 125 .Xr cron 8 ;
 126 the random delay serves to minimize the probability that
 127 a large number of machines will simultaneously attempt to
 128 fetch updates.
 129 .It extract
 130 Extract a ports tree, replacing existing files and directories.
 131 NOTE: This will remove anything occupying the location where
 132 files or directories are being extracted; in particular, any
 133 changes made locally to the ports tree (for example, adding new
 134 patches) will be silently obliterated.
 135 .Pp
 136 Only run this command to initialize your portsnap-maintained
 137 ports tree for the first time, if you wish to start over with
 138 a clean, completely unmodified tree, or if you wish to extract
 139 a specific part of the tree (using the
 140 .Ar path
 141 option).
 142 .It update
 143 Update a ports tree extracted using the
 144 .Cm extract
 145 command.
 146 You must run this command to apply changes to your ports tree
 147 after downloading updates via the
 148 .Cm fetch
 149 or
 150 .Cm cron
 151 commands.
 152 Again, note that in the parts of the ports tree which are being
 153 updated, any local changes or additions will be removed.
 154 .El
 155 .Sh TIPS
 156 .Bl -bullet
 157 .It
 158 If your clock is set to local time, adding the line
 159 .Pp
 160 .Dl 0 3 * * * root /usr/sbin/portsnap cron
 161 .Pp
 162 to /etc/crontab is a good way to make sure you always have
 163 an up-to-date snapshot of the ports tree available which
 164 can quickly be extracted into
 165 .Pa /usr/ports .
 166 If your clock is set to UTC, please pick a random time other
 167 than 3AM, to avoid overly imposing an uneven load on the
 168 server(s) hosting the snapshots.
 169 .It
 170 Running
 171 .Nm
 172 .Cm update
 173 from
 174 .Xr cron 8
 175 is a bad idea -- if you are ever installing or updating a
 176 port at the time the cron job runs, you will probably end up
 177 in a mess when
 178 .Nm
 179 updates or removes files which are being used by the port
 180 build.
 181 However, running
 182 .Nm
 183 .Fl I
 184 .Cm update
 185 is probably safe, and can be used together with
 186 .Xr portversion 1
 187 to identify installed software which is out of date.
 188 .It
 189 If you wish to use
 190 .Nm
 191 to keep a large number of machines up to date, you may wish
 192 to set up a caching HTTP proxy.
 193 Since
 194 .Nm
 195 uses
 196 .Xr fetch 1
 197 to download updates, setting the
 198 .Ev HTTP_PROXY
 199 environment variable will direct it to fetch updates from
 200 the given proxy.
 201 This is much more efficient than
 202 .Em mirroring
 203 the files on the portsnap server, since the vast majority
 204 of files are not needed by any particular client.
 205 .El
 206 .Sh PRIVACY NOTICE
 207 As an unavoidable part of its operation, a machine running
 208 .Nm
 209 will make its public IP address and the list of files it fetches
 210 available to the server from which it fetches updates.
 211 Using these it may be possible to recognize a machine over an extended
 212 period of time, determine when it is updated, and identify which
 213 portions of the FreeBSD ports tree, if any, are being ignored using
 214 "REFUSE" directives in
 215 .Pa portsnap.conf .
 216 In addition, the FreeBSD release level is transmitted to the server.
 217 .Pp
 218 Statistical data generated from information collected in this manner
 219 may be published, but only in aggregate and after anonymizing the
 220 individual systems.
 221 .Sh FILES
 222 .Bl -tag -width "/etc/portsnap.conf"
 223 .It /etc/portsnap.conf
 224 Default location of the portsnap configuration file.
 225 .It /var/db/portsnap
 226 Default location where compressed snapshots are stored.
 227 .It /usr/ports
 228 Default location where the ports tree is extracted.
 229 .El
 230 .Sh SEE ALSO
 231 .Xr fetch 1 ,
 232 .Xr sha256 1 ,
 233 .Xr fetch 3 ,
 234 .Xr portsnap.conf 5
 235 .Sh AUTHORS
 236 .An Colin Percival Aq cperciva@FreeBSD.org