2 .\" Copyright 2004-2005 Colin Percival
3 .\" All rights reserved
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted providing that the following conditions
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.
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.
28 .Dd September 28, 2012
33 .Nd fetch and extract compressed snapshots of the ports tree
48 tool is used to fetch and update compressed snapshots
51 ports tree, and extract and update an
52 uncompressed ports tree.
54 In a normal update operation,
56 will routinely restore modified files to their unmodified state and
57 delete unrecognized local files.
58 This behavior is different to
63 The following options are supported:
64 .Bl -tag -width "-f conffile"
66 Store working files (e.g.\& downloaded updates) in
69 .Pa /var/db/portsnap ,
70 or as given in the configuration file.)
72 Read the configuration from
75 .Pa /etc/portsnap.conf )
79 command, update INDEX files, but not the rest of the ports tree.
81 Expect a public key with given SHA256 hash.
82 (default: read value from configuration file.)
84 Merge the specified local describes file into the INDEX files being
88 should be generated by running
90 in each of the local port directories.
92 When extracting or updating an uncompressed snapshot,
93 operate on the directory
97 or as given in the configuration file.)
99 Fetch files from the specified server or server pool.
100 (default: portsnap.FreeBSD.org, or as given in the
105 command only, operate only on parts of the ports tree starting with
111 would extract sysutils/portsman, sysutils/portsnap,
112 sysutils/portupgrade, etc.)
117 can be any one of the following:
118 .Bl -tag -width "-f conffile"
120 Fetch a compressed snapshot of the ports tree, or update
121 the existing snapshot.
122 This command should only be used interactively; for
123 non-interactive use, you should use the
127 Sleep a random amount of time between 1 and 3600 seconds,
128 then operate as if the
130 command was specified.
131 As the name suggests, this command is designed for running
134 the random delay serves to minimize the probability that
135 a large number of machines will simultaneously attempt to
138 Extract a ports tree, replacing existing files and directories.
139 NOTE: This will remove anything occupying the location where
140 files or directories are being extracted; in particular, any
141 changes made locally to the ports tree (for example, adding new
142 patches) will be silently obliterated.
144 Only run this command to initialize your portsnap-maintained
145 ports tree for the first time, if you wish to start over with
146 a clean, completely unmodified tree, or if you wish to extract
147 a specific part of the tree (using the
151 Update a ports tree extracted using the
154 You must run this command to apply changes to your ports tree
155 after downloading updates via the
160 Again, note that in the parts of the ports tree which are being
161 updated, any local changes or additions will be removed.
166 If your clock is set to local time, adding the line
168 .Dl 0 3 * * * root /usr/sbin/portsnap cron
170 to /etc/crontab is a good way to make sure you always have
171 an up-to-date snapshot of the ports tree available which
172 can quickly be extracted into
174 If your clock is set to UTC, please pick a random time other
175 than 3AM, to avoid overly imposing an uneven load on the
176 server(s) hosting the snapshots.
184 does not apply the changes that were received: they only download
186 To apply the changes, you must follow these commands with
192 command is normally run by hand at a time when you are sure that
193 no one is manually working in the ports tree.
200 is a bad idea -- if you are ever installing or updating a
201 port at the time the cron job runs, you will probably end up
204 updates or removes files which are being used by the port
210 is probably safe, and can be used together with
212 to identify installed software which is out of date.
216 to keep a large number of machines up to date, you may wish
217 to set up a caching HTTP proxy.
222 to download updates, setting the
224 environment variable will direct it to fetch updates from
226 This is much more efficient than
228 the files on the portsnap server, since the vast majority
229 of files are not needed by any particular client.
232 As an unavoidable part of its operation, a machine running
234 will make its public IP address and the list of files it fetches
235 available to the server from which it fetches updates.
236 Using these it may be possible to recognize a machine over an extended
237 period of time, determine when it is updated, and identify which
238 portions of the FreeBSD ports tree, if any, are being ignored using
239 "REFUSE" directives in
241 In addition, the FreeBSD release level is transmitted to the server.
243 Statistical data generated from information collected in this manner
244 may be published, but only in aggregate and after anonymizing the
247 .Bl -tag -width "/etc/portsnap.conf"
248 .It /etc/portsnap.conf
249 Default location of the portsnap configuration file.
251 Default location where compressed snapshots are stored.
253 Default location where the ports tree is extracted.
261 .An Colin Percival Aq cperciva@FreeBSD.org