Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PORTSNAP(8)		    System Manager's Manual		   PORTSNAP(8)

NAME
       portsnap	-- fetch and extract compressed	snapshots of the ports tree

SYNOPSIS
       portsnap	 [-I]  [-d  workdir]  [-f  conffile]  [-k  KEY]	 [-l descfile]
		[-p portsdir] [-s server] command ... [path]

DESCRIPTION
       The portsnap tool is used to fetch and update compressed	 snapshots  of
       the  FreeBSD  ports  tree, and extract and update an uncompressed ports
       tree.

       In a normal update operation, portsnap will routinely restore  modified
       files to	their unmodified state and delete unrecognized local files.

OPTIONS
       The following options are supported:

       -d workdir   Store  working files (e.g. downloaded updates) in workdir.
		    (default: /var/db/portsnap,	or as given in the  configura-
		    tion file.)

       -f conffile  Read   the	 configuration	 from	conffile.    (default:
		    /usr/local/etc/portsnap.conf)

       -I	    For	the update command, update INDEX files,	 but  not  the
		    rest of the	ports tree.

       -k KEY	    Expect  a  public  key  with given SHA256 hash.  (default:
		    read value from configuration file.)

       -l descfile  Merge the specified	local describes	file  into  the	 INDEX
		    files  being  built.   The descfile	should be generated by
		    running make describe in each of the local	port  directo-
		    ries.

       -p portsdir  When  extracting or	updating an uncompressed snapshot, op-
		    erate on the directory portsdir.   (default:  /usr/ports/,
		    or as given	in the configuration file.)

       -s server    Fetch  files  from	the  specified	server or server pool.
		    (default: portsnap.FreeBSD.org, or as given	in the config-
		    uration file.)

       path	    For	extract	command	only, operate only  on	parts  of  the
		    ports  tree	 starting  with	 path.	(e.g. portsnap extract
		    sysutils/port  would  extract   sysutils/portsman,	 sysu-
		    tils/portsnap, sysutils/portupgrade, etc.)

       --interactive
		    override auto-detection of calling process.	 Only use this
		    when  calling  portsnap  from an interactive, non-terminal
		    application. (Cron jobs are	particularly  bad  since  they
		    cause load spikes on the Portsnap mirrors.)

COMMANDS
       The command can be any one of the following:

       fetch	    Fetch  a  compressed snapshot of the ports tree, or	update
		    the	existing snapshot.  This command should	only  be  used
		    interactively; for non-interactive use, you	should use the
		    cron command.

       cron	    Sleep  a random amount of time between 1 and 3600 seconds,
		    then operate as if the fetch command  was  specified.   As
		    the	 name  suggests,  this command is designed for running
		    from cron(8); the random  delay  serves  to	 minimize  the
		    probability	 that a	large number of	machines will simulta-
		    neously attempt to fetch updates.

       extract	    Extract a ports tree, replacing existing files and	direc-
		    tories.  NOTE: This	will remove anything occupying the lo-
		    cation  where files	or directories are being extracted; in
		    particular,	any changes made locally  to  the  ports  tree
		    (for  example, adding new patches) will be silently	oblit-
		    erated.

		    Only run this command to  initialize  your	portsnap-main-
		    tained ports tree for the first time, if you wish to start
		    over  with	a clean, completely unmodified tree, or	if you
		    wish to extract a specific part of	the  tree  (using  the
		    path option).

       update	    Update  a  ports tree extracted using the extract command.
		    You	must run this command to apply changes to  your	 ports
		    tree  after	downloading updates via	the fetch or cron com-
		    mands.  Again, note	that in	the parts of  the  ports  tree
		    which  are	being  updated,	any local changes or additions
		    will be removed.

       auto	    Run	fetch or cron depending	on whether stdin is  a	termi-
		    nal;  then	run  update  or	 extract  depending on whether
		    portsdir exists.

TIPS
       o   If your clock is set	to local time, adding the line

		 0 3 * * * root	/usr/local/sbin/portsnap cron

	   to /etc/crontab is a	good way to make sure you always have  an  up-
	   to-date  snapshot  of the ports tree	available which	can quickly be
	   extracted into /usr/ports.  If your clock is	 set  to  UTC,	please
	   pick	 a random time other than 3AM, to avoid	overly imposing	an un-
	   even	load on	the server(s) hosting the snapshots.

	   Note	that running portsnap cron or portsnap fetch  does  not	 apply
	   the	changes	that were received: they only download them.  To apply
	   the changes,	you must follow	these commands with  portsnap  update.
	   The	portsnap update	command	is normally run	by hand	at a time when
	   you are sure	that no	one is manually	working	in the ports tree.

       o   Running portsnap update from	cron(8)	is a bad idea --  if  you  are
	   ever	 installing  or	updating a port	at the time the	cron job runs,
	   you will probably end up in a mess when portsnap updates or removes
	   files which are being used by the  port  build.   However,  running
	   portsnap  -I	update is probably safe, and can be used together with
	   pkg-version(8) to identify installed	software which is out of date.

       o   If you wish to use portsnap to keep a large number of  machines  up
	   to  date,  you  may	wish  to  set  up a caching HTTP proxy.	 Since
	   portsnap uses fetch(1) to download updates, setting the  HTTP_PROXY
	   environment variable	will direct it to fetch	updates	from the given
	   proxy.  This	is much	more efficient than mirroring the files	on the
	   portsnap server, since the vast majority of files are not needed by
	   any particular client.

PRIVACY	NOTICE
       As  an  unavoidable  part  of its operation, a machine running portsnap
       will make its public IP address and the list of files it	fetches	avail-
       able to the server from which it	fetches	updates.  Using	these  it  may
       be possible to recognize	a machine over an extended period of time, de-
       termine	when it	is updated, and	identify which portions	of the FreeBSD
       ports tree, if any, are being  ignored  using  "REFUSE"	directives  in
       portsnap.conf.

       Statistical  data  generated  from information collected	in this	manner
       may be published, but only in aggregate and after anonymizing the indi-
       vidual systems.

FILES
       /usr/local/etc/portsnap.conf  Default location of the portsnap configu-
				     ration file.

       /var/db//portsnap	     Default location where  compressed	 snap-
				     shots are stored.

       /usr/ports		     Default  location where the ports tree is
				     extracted.

SEE ALSO
       fetch(1)	fetch(3) portsnap.conf(5) sha256(1)

AUTHORS
       Colin Percival <cperciva@FreeBSD.org>

FreeBSD				 July 1, 2018			   PORTSNAP(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | TIPS | PRIVACY NOTICE | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=portsnap&sektion=8&manpath=FreeBSD+14.0-RELEASE+and+Ports>

home | help