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 6, 2020
  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 signature checking is enabled, then the correct signature file
  73 must exist and the signature valid before the package will be installed.
  74 If the
  75 .Fl f
  76 flag is specified, then
  77 .Xr pkg 8
  78 will be installed regardless if it is already installed.
  79 .It Nm Fl N
  80 Do not bootstrap, just determine if
  81 .Xr pkg 8
  82 is actually installed or not.
  83 Returns 0 and the number of packages installed
  84 if it is, otherwise 1.
  85 .It Nm Li bootstrap Op Fl f
  86 Attempt to bootstrap and do not forward anything to
  87 .Xr pkg 8
  88 after it is installed.
  89 If the
  90 .Fl f
  91 flag is specified, then
  92 .Xr pkg 8
  93 will be fetched and installed regardless if it is already installed.
  94 .El
  95 .Sh CONFIGURATION
  96 Configuration varies in whether it is in a repository configuration file
  97 or the global configuration file.
  98 .Pp
  99 Repository configuration can be stored in
 100 .Pa /etc/pkg/FreeBSD.conf
 101 in the following format:
 102 .Bd -literal -offset indent
 103 FreeBSD: {
 104   url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 105   mirror_type: "srv",
 106   signature_type: "none",
 107   fingerprints: "/usr/share/keys/pkg",
 108   enabled: yes
 109 }
 110 .Ed
 111 .Bl -tag -width signature_type -compact
 112 .It url
 113 Refer to
 114 .Dv PACKAGESITE
 115 in
 116 .Sx ENVIRONMENT
 117 .It mirror_type
 118 Refer to
 119 .Dv MIRROR_TYPE
 120 in
 121 .Sx ENVIRONMENT
 122 .It signature_type
 123 Refer to
 124 .Dv SIGNATURE_TYPE
 125 in
 126 .Sx ENVIRONMENT
 127 .It fingerprints
 128 Refer to
 129 .Dv FINGERPRINTS
 130 in
 131 .Sx ENVIRONMENT
 132 .It enabled
 133 Defines whether this repository should be used or not.
 134 Valid values are
 135 .Dv yes ,
 136 .Dv true ,
 137 .Dv 1 ,
 138 .Dv no ,
 139 .Dv false ,
 140 .Dv 0 .
 141 .El
 142 .Pp
 143 Global configuration can be stored in
 144 .Pa /usr/local/etc/pkg.conf
 145 in the following format:
 146 .Bd -literal -offset indent
 147 PACKAGESITE: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
 148 MIRROR_TYPE: "srv",
 149 SIGNATURE_TYPE: "none",
 150 FINGERPRINTS: "/usr/share/keys/pkg",
 151 ASSUME_ALWAYS_YES: "yes"
 152 REPOS_DIR: ["/etc/pkg", "/usr/local/etc/pkg/repos"]
 153 .Ed
 154 .Pp
 155 Reference
 156 .Sx ENVIRONMENT
 157 for each variable.
 158 .Sh ENVIRONMENT
 159 The following environment variables can be set to override the settings
 160 from the
 161 .Pa pkg.conf
 162 file used.
 163 .Bl -tag -width "ASSUME_ALWAYS_YES"
 164 .It Ev MIRROR_TYPE
 165 This defines which mirror type should be used.
 166 Valid values are
 167 .Dv SRV ,
 168 .Dv HTTP ,
 169 .Dv NONE .
 170 .It Ev ABI
 171 This defines the ABI for the package to be installed.
 172 Default ABI is determined from
 173 .Pa /bin/sh .
 174 .It Ev ASSUME_ALWAYS_YES
 175 If set, no confirmation will be asked when bootstrapping
 176 .Xr pkg 8 .
 177 .It Ev SIGNATURE_TYPE
 178 If set to
 179 .Dv FINGERPRINTS
 180 then a signature will be required and validated against known
 181 certificate fingerprints when bootstrapping
 182 .Xr pkg 8 .
 183 .It Ev FINGERPRINTS
 184 If
 185 .Sy SIGNATURE_TYPE
 186 is set to
 187 .Dv FINGERPRINTS
 188 this value should be set to the directory path where known fingerprints are
 189 located.
 190 .It Ev PACKAGESITE
 191 The URL that
 192 .Xr pkg 8
 193 and other packages
 194 will be fetched from.
 195 .It Ev REPOS_DIR
 196 Comma-separated list of directories that should be searched for repository
 197 configuration files.
 198 .El
 199 .Sh FILES
 200 Configuration is read from the files in the listed order.
 201 This path can be changed by setting
 202 .Sy REPOS_DIR .
 203 The last enabled repository is the one used for bootstrapping
 204 .Xr pkg 8 .
 205 .Bl -tag -width "/usr/local/etc/pkg/repos/*.conf"
 206 .It Pa /usr/local/etc/pkg.conf
 207 .It Pa /etc/pkg/FreeBSD.conf
 208 .It Pa /usr/local/etc/pkg/repos/*.conf
 209 .El
 210 .Sh EXAMPLES
 211 Some examples are listed here.
 212 The full list of available commands are available in
 213 .Xr pkg 8
 214 once it is bootstrapped.
 215 .Pp
 216 Search for a package:
 217 .Dl $ pkg search perl
 218 .Pp
 219 Install a package:
 220 .Dl % pkg install perl
 221 .Pp
 222 List installed packages:
 223 .Dl $ pkg info
 224 .Pp
 225 Upgrade from remote repository:
 226 .Dl % pkg upgrade
 227 .Pp
 228 List non-automatic packages:
 229 .Dl $ pkg query -e '%a = 0' %o
 230 .Pp
 231 List automatic packages:
 232 .Dl $ pkg query -e '%a = 1' %o
 233 .Pp
 234 Delete an installed package:
 235 .Dl % pkg delete perl
 236 .Pp
 237 Remove unneeded dependencies:
 238 .Dl % pkg autoremove
 239 .Pp
 240 Change a package from automatic to non-automatic, which will prevent
 241 .Ic autoremove
 242 from removing it:
 243 .Dl % pkg set -A 0 perl
 244 .Pp
 245 Change a package from non-automatic to automatic, which will make
 246 .Ic autoremove
 247 allow it be removed once nothing depends on it:
 248 .Dl % pkg set -A 1 perl
 249 .Pp
 250 Create package file from an installed package:
 251 .Dl % pkg create -o /usr/ports/packages/All perl
 252 .Pp
 253 Determine which package installed a file:
 254 .Dl $ pkg which /usr/local/bin/perl
 255 .Pp
 256 Audit installed packages for security advisories:
 257 .Dl $ pkg audit
 258 .Pp
 259 Check installed packages for checksum mismatches:
 260 .Dl # pkg check -s -a
 261 .Pp
 262 Check for missing dependencies:
 263 .Dl # pkg check -d -a
 264 .Sh SEE ALSO
 265 .Xr ports 7 ,
 266 .Xr pkg 8
 267 .Sh HISTORY
 268 The
 269 .Nm
 270 command first appeared in
 271 .Fx 9.1 .
 272 It became the default package tool in
 273 .Fx 10.0 ,
 274 replacing the
 275 pkg_install suite of tools
 276 .Xr pkg_add 1 ,
 277 .Xr pkg_info 1 and
 278 .Xr pkg_create 1 .