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 December 12, 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 REPOS_DIR: ["/etc/pkg", "/usr/local/etc/pkg/repos"]
 156 .Ed
 157 .Pp
 158 Reference
 159 .Sx ENVIRONMENT
 160 for each variable.
 161 .Sh ENVIRONMENT
 162 The following environment variables can be set to override the settings
 163 from the
 164 .Pa pkg.conf
 165 file used.
 166 .Bl -tag -width "ASSUME_ALWAYS_YES"
 167 .It Ev MIRROR_TYPE
 168 This defines which mirror type should be used.
 169 Valid values are
 170 .Dv SRV ,
 171 .Dv HTTP ,
 172 .Dv NONE .
 173 .It Ev ABI
 174 This defines the ABI for the package to be installed.
 175 Default ABI is determined from
 176 .Pa /bin/sh .
 177 .It Ev ASSUME_ALWAYS_YES
 178 If set, no confirmation will be asked when bootstrapping
 179 .Xr pkg 8 .
 180 .It Ev SIGNATURE_TYPE
 181 If set to
 182 .Dv FINGERPRINTS
 183 then a signature will be required and validated against known
 184 certificate fingerprints when bootstrapping
 185 .Xr pkg 8 .
 186 .It Ev FINGERPRINTS
 187 If
 188 .Sy SIGNATURE_TYPE
 189 is set to
 190 .Dv FINGERPRINTS
 191 this value should be set to the directory path where known fingerprints are
 192 located.
 193 .It Ev PACKAGESITE
 194 The URL that
 195 .Xr pkg 8
 196 and other packages
 197 will be fetched from.
 198 .It Ev REPOS_DIR
 199 Comma-separated list of directories that should be searched for repository
 200 configuration files.
 201 .El
 202 .Sh FILES
 203 Configuration is read from the files in the listed order.
 204 This path can be changed by setting
 205 .Sy REPOS_DIR .
 206 The last enabled repository is the one used for bootstrapping
 207 .Xr pkg 8 .
 208 .Bl -tag -width "/usr/local/etc/pkg/repos/*.conf"
 209 .It Pa /usr/local/etc/pkg.conf
 210 .It Pa /etc/pkg/FreeBSD.conf
 211 .It Pa /usr/local/etc/pkg/repos/*.conf
 212 .El
 213 .Sh EXAMPLES
 214 Some examples are listed here.
 215 The full list of available commands are available in
 216 .Xr pkg 8
 217 once it is bootstrapped.
 218 .Pp
 219 Search for a package:
 220 .Dl $ pkg search perl
 221 .Pp
 222 Install a package:
 223 .Dl % pkg install perl
 224 .Pp
 225 List installed packages:
 226 .Dl $ pkg info
 227 .Pp
 228 Upgrade from remote repository:
 229 .Dl % pkg upgrade
 230 .Pp
 231 List non-automatic packages:
 232 .Dl $ pkg query -e '%a = 0' %o
 233 .Pp
 234 List automatic packages:
 235 .Dl $ pkg query -e '%a = 1' %o
 236 .Pp
 237 Delete an installed package:
 238 .Dl % pkg delete perl
 239 .Pp
 240 Remove unneeded dependencies:
 241 .Dl % pkg autoremove
 242 .Pp
 243 Change a package from automatic to non-automatic, which will prevent
 244 .Ic autoremove
 245 from removing it:
 246 .Dl % pkg set -A 0 perl
 247 .Pp
 248 Change a package from non-automatic to automatic, which will make
 249 .Ic autoremove
 250 allow it be removed once nothing depends on it:
 251 .Dl % pkg set -A 1 perl
 252 .Pp
 253 Create package file from an installed package:
 254 .Dl % pkg create -o /usr/ports/packages/All perl
 255 .Pp
 256 Determine which package installed a file:
 257 .Dl $ pkg which /usr/local/bin/perl
 258 .Pp
 259 Audit installed packages for security advisories:
 260 .Dl $ pkg audit
 261 .Pp
 262 Check installed packages for checksum mismatches:
 263 .Dl # pkg check -s -a
 264 .Pp
 265 Check for missing dependencies:
 266 .Dl # pkg check -d -a
 267 .Sh SEE ALSO
 268 .Xr ports 7 ,
 269 .Xr pkg 8
 270 .Sh HISTORY
 271 The
 272 .Nm
 273 command first appeared in
 274 .Fx 9.1 .
 275 It became the default package tool in
 276 .Fx 10.0 ,
 277 replacing the
 278 pkg_install suite of tools
 279 .Xr pkg_add 1 ,
 280 .Xr pkg_info 1 and
 281 .Xr pkg_create 1 .