usr.sbin/pkg/pkg.7

   1 .\" Copyright (c) 2013 Bryan Drewery <bdrewery@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 19, 2013
  28 .Dt PKG 7
  29 .Os
  30 .Sh NAME
  31 .Nm pkg
  32 .Nd a utility for manipulating packages
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Ao Ar command Ac
  36 .Nm
  37 add
  38 .Op Fl f
  39 .Ao Pa pkg.txz Ac
  40 .Nm
  41 .Fl N
  42 .Nm
  43 bootstrap
  44 .Op Fl f
  45 .Sh DESCRIPTION
  46 .Nm
  47 is the package management tool.
  48 It is used to manage local packages installed from
  49 .Xr ports 7
  50 and install/upgrade packages from remote repositories.
  51 .Pp
  52 To avoid backwards incompatibility issues, the actual
  53 .Xr pkg 8
  54 tool is not installed in the base system.
  55 The first time invoked,
  56 .Nm
  57 will bootstrap the real
  58 .Xr pkg 8
  59 from a remote repository.
  60 .Bl -tag -width "pkg bootstrap"
  61 .It Nm Ao Ar command Ac
  62 If
  63 .Xr pkg 8
  64 is not installed yet, it will be fetched, have its signature verified,
  65 installed, and then have the original command forwarded to it.
  66 If already installed, the command requested will be forwarded to the real
  67 .Xr pkg 8 .
  68 .It Nm Li add Oo Fl f Oc Ao Pa pkg.txz Ac
  69 Install
  70 .Xr pkg 8
  71 from a local package instead of fetching from remote.
  72 If a
  73 .Pa pkg.txz.sig
  74 file exists and
  75 signature checking is enabled, then the signature will be verified
  76 before installing the package.
  77 If the
  78 .Fl f
  79 flag is specified, then
  80 .Xr pkg 8
  81 will be installed regardless if it is already installed.
  82 .It Nm Fl N
  83 Do not bootstrap, just determine if
  84 .Xr pkg 8
  85 is actually installed or not.
  86 Returns 0 and the number of packages installed
  87 if it is, otherwise 1.
  88 .It Nm Li bootstrap Op Fl f
  89 Attempt to bootstrap and do not forward anything to
  90 .Xr pkg 8
  91 after it is installed.
  92 If the
  93 .Fl f
  94 flag is specified, then
  95 .Xr pkg 8
  96 will be fetched and installed regardless if it is already installed.
  97 .El
  98 .Sh CONFIGURATION
  99 Configuration varies in whether it is in a repository configuration file
 100 or the global configuration file.
 101 .Pp
 102 Repository configuration can be stored in
 103 .Pa /etc/pkg/FreeBSD.conf
 104 in the following format:
 105 .Bd -literal -offset indent
 106 FreeBSD: {
 107   url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 108   mirror_type: "srv",
 109   signature_type: "none",
 110   fingerprints: "/usr/share/keys/pkg",
 111   enabled: yes
 112 }
 113 .Ed
 114 .Bl -tag -width signature_type -compact
 115 .It url
 116 Refer to
 117 .Dv PACKAGESITE
 118 in
 119 .Sx ENVIRONMENT
 120 .It mirror_type
 121 Refer to
 122 .Dv MIRROR_TYPE
 123 in
 124 .Sx ENVIRONMENT
 125 .It signature_type
 126 Refer to
 127 .Dv SIGNATURE_TYPE
 128 in
 129 .Sx ENVIRONMENT
 130 .It fingerprints
 131 Refer to
 132 .Dv FINGERPRINTS
 133 in
 134 .Sx ENVIRONMENT
 135 .It enabled
 136 Defines whether this repository should be used or not.
 137 Valid values are
 138 .Dv yes ,
 139 .Dv true ,
 140 .Dv 1 ,
 141 .Dv no ,
 142 .Dv false ,
 143 .Dv 0 .
 144 .El
 145 .Pp
 146 Global configuration can be stored in
 147 .Pa /usr/local/etc/pkg.conf
 148 in the following format:
 149 .Bd -literal -offset indent
 150 PACKAGESITE: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 151 MIRROR_TYPE: "srv",
 152 SIGNATURE_TYPE: "none",
 153 FINGERPRINTS: "/usr/share/keys/pkg",
 154 ASSUME_ALWAYS_YES: "yes"
 155 .Ed
 156 .Pp
 157 Reference
 158 .Sx ENVIRONMENT
 159 for each variable.
 160 .Sh ENVIRONMENT
 161 The following environment variables can be set to override the settings
 162 from the
 163 .Pa pkg.conf
 164 file used.
 165 .Bl -tag -width "ASSUME_ALWAYS_YES"
 166 .It Ev MIRROR_TYPE
 167 This defines which mirror type should be used.
 168 Valid values are
 169 .Dv SRV ,
 170 .Dv HTTP ,
 171 .Dv NONE .
 172 .It Ev ABI
 173 This defines the ABI for the package to be installed.
 174 Default ABI is determined from
 175 .Pa /bin/sh .
 176 .It Ev ASSUME_ALWAYS_YES
 177 If set, no confirmation will be asked when bootstrapping
 178 .Xr pkg 8 .
 179 .It Ev SIGNATURE_TYPE
 180 If set to
 181 .Dv FINGERPRINTS
 182 then a signature will be required and validated against known
 183 certificate fingerprints when bootstrapping
 184 .Xr pkg 8 .
 185 .It Ev FINGERPRINTS
 186 If
 187 .Sy SIGNATURE_TYPE
 188 is set to
 189 .Dv FINGERPRINTS
 190 this value should be set to the directory path where known fingerprints are
 191 located.
 192 .It Ev PACKAGESITE
 193 The URL that
 194 .Xr pkg 8
 195 and other packages
 196 will be fetched from.
 197 .El
 198 .Sh FILES
 199 Configuration is read from the files in the listed order.
 200 The first enabled repository is the one used for bootstrapping
 201 .Xr pkg 8 .
 202 .Bl -tag -width "/usr/local/etc/pkg/repos/*.conf"
 203 .It Pa /usr/local/etc/pkg.conf
 204 .It Pa /etc/pkg/FreeBSD.conf
 205 .El
 206 .Sh EXAMPLES
 207 Some examples are listed here.
 208 The full list of available commands are available in
 209 .Xr pkg 8
 210 once it is bootstrapped.
 211 .Pp
 212 Search for a package:
 213 .Dl $ pkg search perl
 214 .Pp
 215 Install a package:
 216 .Dl % pkg install perl
 217 .Pp
 218 List installed packages:
 219 .Dl $ pkg info
 220 .Pp
 221 Upgrade from remote repository:
 222 .Dl % pkg upgrade
 223 .Pp
 224 List non-automatic packages:
 225 .Dl $ pkg query -e '%a = 0' %o
 226 .Pp
 227 List automatic packages:
 228 .Dl $ pkg query -e '%a = 1' %o
 229 .Pp
 230 Delete an installed package:
 231 .Dl % pkg delete perl
 232 .Pp
 233 Remove unneeded dependencies:
 234 .Dl % pkg autoremove
 235 .Pp
 236 Change a package from automatic to non-automatic, which will prevent
 237 .Ic autoremove
 238 from removing it:
 239 .Dl % pkg set -A 0 perl
 240 .Pp
 241 Change a package from non-automatic to automatic, which will make
 242 .Ic autoremove
 243 allow it be removed once nothing depends on it:
 244 .Dl % pkg set -A 1 perl
 245 .Pp
 246 Create package file from an installed package:
 247 .Dl % pkg create -o /usr/ports/packages/All perl
 248 .Pp
 249 Determine which package installed a file:
 250 .Dl $ pkg which /usr/local/bin/perl
 251 .Pp
 252 Audit installed packages for security advisories:
 253 .Dl $ pkg audit
 254 .Pp
 255 Check installed packages for checksum mismatches:
 256 .Dl # pkg check -s -a
 257 .Pp
 258 Check for missing dependencies:
 259 .Dl # pkg check -d -a
 260 .Sh SEE ALSO
 261 .Xr ports 7 ,
 262 .Xr pkg 8
 263 .Sh HISTORY
 264 The
 265 .Nm
 266 command first appeared in
 267 .Fx 9.1 .
 268 It became the default package tool in
 269 .Fx 10.0 ,
 270 replacing the
 271 pkg_install suite of tools
 272 .Xr pkg_add 1 ,
 273 .Xr pkg_info 1 and
 274 .Xr pkg_create 1 .