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 .Dd August 24, 2022
  26 .Dt PKG 7
  27 .Os
  28 .Sh NAME
  29 .Nm pkg
  30 .Nd a utility for manipulating packages
  31 .Sh SYNOPSIS
  32 .Nm
  33 .Op Fl d
  34 .Ar command ...
  35 .Nm
  36 .Cm add
  37 .Op Fl dfy
  38 .Op Fl r Ar reponame
  39 .Ar pkg.txz
  40 .Nm
  41 .Fl N
  42 .Nm
  43 .Op Fl 46d
  44 .Cm bootstrap
  45 .Op Fl fy
  46 .Op Fl r Ar reponame
  47 .Sh DESCRIPTION
  48 .Nm
  49 is the package management tool.
  50 It is used to manage local packages installed from
  51 .Xr ports 7
  52 and install/upgrade packages from remote repositories.
  53 .Pp
  54 To avoid backwards incompatibility issues, the actual
  55 .Xr pkg 8
  56 tool is not installed in the base system.
  57 The first time invoked,
  58 .Nm
  59 will bootstrap the real
  60 .Xr pkg 8
  61 from a remote repository.
  62 .Bl -tag
  63 .It Nm Ar command ...
  64 If
  65 .Xr pkg 8
  66 is not installed yet, it will be fetched, have its signature verified,
  67 installed, and then have the original command forwarded to it.
  68 If already installed, the command requested will be forwarded to the real
  69 .Xr pkg 8 .
  70 .It Nm Cm add Oo Fl fy Oc Oo Fl r Ar reponame Oc Ar pkg.txz
  71 Install
  72 .Xr pkg 8
  73 from a local package instead of fetching from remote.
  74 If signature checking is enabled, then the correct signature file
  75 must exist and the signature valid before the package will be installed.
  76 If the
  77 .Fl f
  78 flag is specified, then
  79 .Xr pkg 8
  80 will be installed regardless if it is already installed.
  81 If the
  82 .Fl y
  83 flag is specified, no confirmation will be asked when bootstrapping
  84 .Xr pkg 8 .
  85 .Pp
  86 If a
  87 .Ar reponame
  88 has been specified, then the signature configuration for that repository will be
  89 used.
  90 .It Nm Fl N
  91 Do not bootstrap, just determine if
  92 .Xr pkg 8
  93 is actually installed or not.
  94 Returns 0 and the number of packages installed
  95 if it is, otherwise 1.
  96 .It Nm Oo Fl 46 Oc Cm bootstrap Oo Fl fy Oc \
  97 Oo Fl r Ar reponame Oc
  98 Attempt to bootstrap and do not forward anything to
  99 .Xr pkg 8
 100 after it is installed.
 101 With
 102 .Fl 4
 103 and
 104 .Fl 6 ,
 105 .Nm
 106 will force IPv4 or IPv6 respectively to fetch
 107 .Xr pkg 8
 108 and its signatures as needed.
 109 If the
 110 .Fl f
 111 flag is specified, then
 112 .Xr pkg 8
 113 will be fetched and installed regardless if it is already installed.
 114 If the
 115 .Fl y
 116 flag is specified, no confirmation will be asked when bootstrapping
 117 .Xr pkg 8 .
 118 .Pp
 119 If a
 120 .Ar reponame
 121 has been specified, then the configuration for that repository will be used.
 122 .El
 123 .Sh OPTIONS
 124 The following options are supported by
 125 .Nm :
 126 .Bl -tag -width indent
 127 .It Fl d, Fl -debug
 128 Show debug information.
 129 May be specified more than once to increase the level of detail.
 130 When specified twice,
 131 .Xr fetch 3
 132 debug output is enabled.
 133 .El
 134 .Sh CONFIGURATION
 135 Configuration varies in whether it is in a repository configuration file
 136 or the global configuration file.
 137 The default repository configuration for
 138 .Fx
 139 is stored in
 140 .Pa /etc/pkg/FreeBSD.conf ,
 141 and additional repository configuration files will be searched for in
 142 .Ev REPOS_DIR ,
 143 or
 144 .Pa /usr/local/etc/pkg/repos
 145 if it is unset.
 146 .Pp
 147 For bootstrapping,
 148 .Nm
 149 will process all repositories that it finds and use the last enabled repository
 150 by default.
 151 .Pp
 152 Repository configuration is stored in the following format:
 153 .Bd -literal -offset indent
 154 FreeBSD: {
 155   url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 156   mirror_type: "srv",
 157   signature_type: "none",
 158   fingerprints: "/usr/share/keys/pkg",
 159   enabled: yes
 160 }
 161 .Ed
 162 .Pp
 163 .Bl -tag -width signature_type -compact
 164 .It url
 165 Refer to
 166 .Dv PACKAGESITE
 167 in
 168 .Sx ENVIRONMENT
 169 .It mirror_type
 170 Refer to
 171 .Dv MIRROR_TYPE
 172 in
 173 .Sx ENVIRONMENT
 174 .It signature_type
 175 Refer to
 176 .Dv SIGNATURE_TYPE
 177 in
 178 .Sx ENVIRONMENT
 179 .It fingerprints
 180 Refer to
 181 .Dv FINGERPRINTS
 182 in
 183 .Sx ENVIRONMENT
 184 .It enabled
 185 Defines whether this repository should be used or not.
 186 Valid values are
 187 .Dv yes ,
 188 .Dv true ,
 189 .Dv 1 ,
 190 .Dv no ,
 191 .Dv false ,
 192 .Dv 0 .
 193 .El
 194 .Pp
 195 Global configuration can be stored in
 196 .Pa /usr/local/etc/pkg.conf
 197 in the following format:
 198 .Bd -literal -offset indent
 199 PACKAGESITE: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 200 MIRROR_TYPE: "srv",
 201 SIGNATURE_TYPE: "none",
 202 FINGERPRINTS: "/usr/share/keys/pkg",
 203 ASSUME_ALWAYS_YES: "yes"
 204 REPOS_DIR: ["/etc/pkg", "/usr/local/etc/pkg/repos"]
 205 .Ed
 206 .Pp
 207 Reference
 208 .Sx ENVIRONMENT
 209 for each variable.
 210 .Sh ENVIRONMENT
 211 The following environment variables can be set to override the settings
 212 from the
 213 .Pa pkg.conf
 214 file used.
 215 .Bl -tag -width "ASSUME_ALWAYS_YES"
 216 .It Ev MIRROR_TYPE
 217 This defines which mirror type should be used.
 218 Valid values are
 219 .Dv SRV ,
 220 .Dv HTTP ,
 221 .Dv NONE .
 222 .It Ev ABI
 223 This defines the ABI for the package to be installed.
 224 Default ABI is determined from
 225 .Pa /bin/sh .
 226 .It Ev ASSUME_ALWAYS_YES
 227 If set, no confirmation will be asked when bootstrapping
 228 .Xr pkg 8 .
 229 .It Ev SIGNATURE_TYPE
 230 If set to
 231 .Dv FINGERPRINTS
 232 then a signature will be required and validated against known
 233 certificate fingerprints when bootstrapping
 234 .Xr pkg 8 .
 235 .It Ev FINGERPRINTS
 236 If
 237 .Sy SIGNATURE_TYPE
 238 is set to
 239 .Dv FINGERPRINTS
 240 this value should be set to the directory path where known fingerprints are
 241 located.
 242 .It Ev PACKAGESITE
 243 The URL that
 244 .Xr pkg 8
 245 and other packages
 246 will be fetched from.
 247 .It Ev REPOS_DIR
 248 Comma-separated list of directories that should be searched for repository
 249 configuration files.
 250 .El
 251 .Sh FILES
 252 Configuration is read from the files in the listed order.
 253 This path can be changed by setting
 254 .Ev REPOS_DIR .
 255 The last enabled repository is the one used for bootstrapping
 256 .Xr pkg 8 .
 257 .Bl -tag -width "/usr/local/etc/pkg/repos/*.conf"
 258 .It Pa /usr/local/etc/pkg.conf
 259 .It Pa /etc/pkg/FreeBSD.conf
 260 .It Pa /usr/local/etc/pkg/repos/*.conf
 261 .El
 262 .Sh EXAMPLES
 263 Some examples are listed here.
 264 The full list of available commands are available in
 265 .Xr pkg 8
 266 once it is bootstrapped.
 267 .Pp
 268 Search for a package:
 269 .Dl $ pkg search perl
 270 .Pp
 271 Install a package:
 272 .Dl % pkg install perl
 273 .Pp
 274 List installed packages:
 275 .Dl $ pkg info
 276 .Pp
 277 Upgrade from remote repository:
 278 .Dl % pkg upgrade
 279 .Pp
 280 List non-automatic packages:
 281 .Dl $ pkg query -e '%a = 0' %o
 282 .Pp
 283 List automatic packages:
 284 .Dl $ pkg query -e '%a = 1' %o
 285 .Pp
 286 Delete an installed package:
 287 .Dl % pkg delete perl
 288 .Pp
 289 Remove unneeded dependencies:
 290 .Dl % pkg autoremove
 291 .Pp
 292 Change a package from automatic to non-automatic, which will prevent
 293 .Xr pkg-autoremove 8
 294 from removing it:
 295 .Dl % pkg set -A 0 perl
 296 .Pp
 297 Change a package from non-automatic to automatic, which will make
 298 .Xr pkg-autoremove 8
 299 allow it be removed once nothing depends on it:
 300 .Dl % pkg set -A 1 perl
 301 .Pp
 302 Create package file from an installed package:
 303 .Dl % pkg create -o /usr/ports/packages/All perl
 304 .Pp
 305 Determine which package installed a file:
 306 .Dl $ pkg which /usr/local/bin/perl
 307 .Pp
 308 Audit installed packages for security advisories:
 309 .Dl $ pkg audit
 310 .Pp
 311 Check installed packages for checksum mismatches:
 312 .Dl # pkg check -s -a
 313 .Pp
 314 Check for missing dependencies:
 315 .Dl # pkg check -d -a
 316 .Sh SEE ALSO
 317 .Xr ports 7 ,
 318 .Xr pkg 8
 319 .Sh HISTORY
 320 The
 321 .Nm
 322 command first appeared in
 323 .Fx 9.1 .
 324 It became the default package tool in
 325 .Fx 10.0 ,
 326 replacing the
 327 pkg_install suite of tools
 328 .Xr pkg_add 1 ,
 329 .Xr pkg_info 1 and
 330 .Xr pkg_create 1 .