portsnap.8 revision 148871
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: head/usr.sbin/portsnap/portsnap/portsnap.8 148871 2005-08-08 20:10:06Z cperciva $ 27.\" 28.Dd January 30, 2005 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 p Ar portsdir 41.Op Fl s Ar server 42.Cm command 43.Op Ar path 44.Sh DESCRIPTION 45The 46.Nm 47tool is used to fetch and update compressed snapshots 48of the FreeBSD ports tree, and extract and update an 49uncompressed ports tree. 50.Sh OPTIONS 51The following options are supported: 52.Bl -tag -width "-f conffile" 53.It Fl d Ar workdir 54Store working files (e.g. downloaded updates) in 55.Ar workdir . 56(default: 57.Pa /var/db/portsnap , 58or as given in the configuration file.) 59.It Fl f Ar conffile 60Read the configuration from from 61.Ar conffile . 62(default: 63.Pa /etc/portsnap.conf ) 64.It Fl I 65For the 66.Cm update 67command, update INDEX files, but not the rest of the ports tree. 68.It Fl k Ar KEY 69Expect a public key with given SHA256 hash. 70(default: read value from configuration file.) 71.It Fl p Ar portsdir 72When extracting or updating an uncompressed snapshot, 73operate on the directory 74.Ar portsdir . 75(default: 76.Pa /usr/ports/ , 77or as given in the configuration file.) 78.It Fl s Ar server 79Fetch files from the specified server or server pool. 80(default: portsnap.FreeBSD.org , or as given in the 81configuration file.) 82.It path 83For 84.Cm extract 85command only, operate only on parts of the ports tree starting with 86.Ar path . 87(e.g. 88.Nm 89.cm extract 90.Ar sysutils/port 91would extract sysutils/portsman, sysutils/portsnap, 92sysutils/portupgrade, etc.) 93.El 94.Sh COMMANDS 95The 96.Cm command 97can be any one of the following: 98.Pp 99.Bl -tag -width "-f conffile" 100.It fetch 101Fetch a compressed snapshot of the ports tree, or update 102the existing snapshot. 103This command should only be used interactively; for 104non-interactive use, you should use the 105.Cm cron 106command. 107.It cron 108Sleep a random amount of time, then operate as if the 109.Cm fetch 110command was specified. 111As the name suggests, this command is designed for running 112from 113.Xr cron 8 ; 114the random delay serves to minimize the probability that 115a large number of machines will simultaneously attempt to 116fetch updates. 117.It extract 118Extract a ports tree, replacing existing files and directories. 119NOTE: This will remove anything occupying the location where 120files or directories are being extracted; in particular, any 121changes made locally to the ports tree (for example, adding new 122patches) will be silently obliterated. 123.Pp 124Only run this command to initialize your portsnap-maintained 125ports tree for the first time, if you wish to start over with 126a clean, completely unmodified tree, or if you wish to extract 127a specific part of the tree (using the 128.Ar path 129option). 130.It update 131Update a ports tree extracted using the 132.Cm extract 133command. 134You must run this command to apply changes to your ports tree 135after downloading updates via the 136.Cm fetch 137or 138.Cm cron 139commands. 140Again, note that in the parts of the ports tree which are being 141updated, any local changes or additions will be removed. 142.El 143.Sh TIPS 144.Bl -bullet 145.It 146If your clock is set to local time, adding the line 147.Pp 148.Dl 0 3 * * * root /usr/sbin/portsnap cron 149.Pp 150to /etc/crontab is a good way to make sure you always have 151an up-to-date snapshot of the ports tree available which 152can quickly be extracted into 153.Pa /usr/ports . 154If your clock is set to UTC, please pick a random time other 155than 3AM, to avoid overly imposing an uneven load on the 156server(s) hosting the snapshots. 157.It 158Running 159.Nm 160.Cm update 161from 162.Xr cron 8 163is a bad idea -- if you're ever installing or updating a 164port at the time the cron job runs, you'll probably end up 165in a mess when 166.Cm 167updates or removes files which are being used by the port 168build. 169However, running 170.Nm 171.Fl I 172.Cm update 173is probably safe, and can be used together with 174.Xr portversion 1 175to identify installed software which is out of date. 176.It 177If you wish to use 178.Nm 179to keep a large number of machines up to date, you may wish 180to set up a caching HTTP proxy. Since 181.Nm 182uses 183.Xr fetch 1 184to download updates, setting the 185.Ev HTTP_PROXY 186environment variable will direct it to fetch updates from 187the given proxy. 188This is much more efficient than 189.Em mirroring 190the files on the portsnap server, since the vast majority 191of files are not needed by any particular client. 192.El 193.Sh FILES 194.Bl -tag -width "/etc/portsnap.conf" 195.It /etc/portsnap.conf 196Default location of the portsnap configuration file. 197.It /var/db/portsnap 198Default location where compressed snapshots are stored. 199.It /usr/ports 200Default location where the ports tree is extracted. 201.El 202.Sh SEE ALSO 203.Xr fetch 1 204.Xr fetch 3 205.Xr portsnap.conf 5 206.Xr sha256 8 207.Sh AUTHORS 208.An Colin Percival Aq cperciva@FreeBSD.org 209