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 October 14, 2012
  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 .Pp
  54 In a normal update operation,
  55 .Nm
  56 will routinely restore modified files to their unmodified state and
  57 delete unrecognized local files.
  58 .Sh OPTIONS
  59 The following options are supported:
  60 .Bl -tag -width "-f conffile"
  61 .It Fl d Ar workdir
  62 Store working files (e.g.\& downloaded updates) in
  63 .Ar workdir .
  64 (default:
  65 .Pa /var/db/portsnap ,
  66 or as given in the configuration file.)
  67 .It Fl f Ar conffile
  68 Read the configuration from
  69 .Ar conffile .
  70 (default:
  71 .Pa /etc/portsnap.conf )
  72 .It Fl I
  73 For the
  74 .Cm update
  75 command, update INDEX files, but not the rest of the ports tree.
  76 .It Fl k Ar KEY
  77 Expect a public key with given SHA256 hash.
  78 (default: read value from configuration file.)
  79 .It Fl l Ar descfile
  80 Merge the specified local describes file into the INDEX files being
  81 built.
  82 The
  83 .Ar descfile
  84 should be generated by running
  85 .Cm make describe
  86 in each of the local port directories.
  87 .It Fl p Ar portsdir
  88 When extracting or updating an uncompressed snapshot,
  89 operate on the directory
  90 .Ar portsdir .
  91 (default:
  92 .Pa /usr/ports/ ,
  93 or as given in the configuration file.)
  94 .It Fl s Ar server
  95 Fetch files from the specified server or server pool.
  96 (default: portsnap.FreeBSD.org, or as given in the
  97 configuration file.)
  98 .It path
  99 For
 100 .Cm extract
 101 command only, operate only on parts of the ports tree starting with
 102 .Ar path .
 103 (e.g.\&
 104 .Nm
 105 .Cm extract
 106 .Ar sysutils/port
 107 would extract sysutils/portsman, sysutils/portsnap,
 108 sysutils/portupgrade, etc.)
 109 .It Fl Fl interactive
 110 override auto-detection of calling process.
 111 Only use this when calling portsnap from an
 112 .Sy interactive, non-terminal application.
 113 (Cron jobs are particularly bad since they cause
 114 load spikes on the Portsnap mirrors.)
 115 .El
 116 .Sh COMMANDS
 117 The
 118 .Cm command
 119 can be any one of the following:
 120 .Bl -tag -width "-f conffile"
 121 .It fetch
 122 Fetch a compressed snapshot of the ports tree, or update
 123 the existing snapshot.
 124 This command should only be used interactively; for
 125 non-interactive use, you should use the
 126 .Cm cron
 127 command.
 128 .It cron
 129 Sleep a random amount of time between 1 and 3600 seconds,
 130 then operate as if the
 131 .Cm fetch
 132 command was specified.
 133 As the name suggests, this command is designed for running
 134 from
 135 .Xr cron 8 ;
 136 the random delay serves to minimize the probability that
 137 a large number of machines will simultaneously attempt to
 138 fetch updates.
 139 .It extract
 140 Extract a ports tree, replacing existing files and directories.
 141 NOTE: This will remove anything occupying the location where
 142 files or directories are being extracted; in particular, any
 143 changes made locally to the ports tree (for example, adding new
 144 patches) will be silently obliterated.
 145 .Pp
 146 Only run this command to initialize your portsnap-maintained
 147 ports tree for the first time, if you wish to start over with
 148 a clean, completely unmodified tree, or if you wish to extract
 149 a specific part of the tree (using the
 150 .Ar path
 151 option).
 152 .It update
 153 Update a ports tree extracted using the
 154 .Cm extract
 155 command.
 156 You must run this command to apply changes to your ports tree
 157 after downloading updates via the
 158 .Cm fetch
 159 or
 160 .Cm cron
 161 commands.
 162 Again, note that in the parts of the ports tree which are being
 163 updated, any local changes or additions will be removed.
 164 .El
 165 .Sh TIPS
 166 .Bl -bullet
 167 .It
 168 If your clock is set to local time, adding the line
 169 .Pp
 170 .Dl 0 3 * * * root /usr/sbin/portsnap cron
 171 .Pp
 172 to
 173 .Pa /etc/crontab
 174 is a good way to make sure you always have
 175 an up-to-date snapshot of the ports tree available which
 176 can quickly be extracted into
 177 .Pa /usr/ports .
 178 If your clock is set to UTC, please pick a random time other
 179 than 3AM, to avoid overly imposing an uneven load on the
 180 server(s) hosting the snapshots.
 181 .Pp
 182 Note that running
 183 .Nm
 184 .Cm cron
 185 or
 186 .Nm
 187 .Cm fetch
 188 does not apply the changes that were received: they only download
 189 them.
 190 To apply the changes, you must follow these commands with
 191 .Nm
 192 .Cm update .
 193 The
 194 .Nm
 195 .Cm update
 196 command is normally run by hand at a time when you are sure that
 197 no one is manually working in the ports tree.
 198 .It
 199 Running
 200 .Nm
 201 .Cm update
 202 from
 203 .Xr cron 8
 204 is a bad idea -- if you are ever installing or updating a
 205 port at the time the cron job runs, you will probably end up
 206 in a mess when
 207 .Nm
 208 updates or removes files which are being used by the port
 209 build.
 210 However, running
 211 .Nm
 212 .Fl I
 213 .Cm update
 214 is probably safe, and can be used together with
 215 .Xr portversion 1
 216 to identify installed software which is out of date.
 217 .It
 218 If you wish to use
 219 .Nm
 220 to keep a large number of machines up to date, you may wish
 221 to set up a caching HTTP proxy.
 222 Since
 223 .Nm
 224 uses
 225 .Xr fetch 1
 226 to download updates, setting the
 227 .Ev HTTP_PROXY
 228 environment variable will direct it to fetch updates from
 229 the given proxy.
 230 This is much more efficient than
 231 .Em mirroring
 232 the files on the portsnap server, since the vast majority
 233 of files are not needed by any particular client.
 234 .El
 235 .Sh PRIVACY NOTICE
 236 As an unavoidable part of its operation, a machine running
 237 .Nm
 238 will make its public IP address and the list of files it fetches
 239 available to the server from which it fetches updates.
 240 Using these it may be possible to recognize a machine over an extended
 241 period of time, determine when it is updated, and identify which
 242 portions of the FreeBSD ports tree, if any, are being ignored using
 243 "REFUSE" directives in
 244 .Pa portsnap.conf .
 245 In addition, the FreeBSD release level is transmitted to the server.
 246 .Pp
 247 Statistical data generated from information collected in this manner
 248 may be published, but only in aggregate and after anonymizing the
 249 individual systems.
 250 .Sh FILES
 251 .Bl -tag -width "/etc/portsnap.conf"
 252 .It Pa /etc/portsnap.conf
 253 Default location of the portsnap configuration file.
 254 .It Pa /var/db/portsnap
 255 Default location where compressed snapshots are stored.
 256 .It Pa /usr/ports
 257 Default location where the ports tree is extracted.
 258 .El
 259 .Sh SEE ALSO
 260 .Xr fetch 1 ,
 261 .Xr sha256 1 ,
 262 .Xr fetch 3 ,
 263 .Xr portsnap.conf 5
 264 .Sh AUTHORS
 265 .An Colin Percival Aq cperciva@FreeBSD.org