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