xref: /freebsd/usr.sbin/pkg/pkg.7 (revision 13de33a5dc2304b13d595d75d48c51793958474f)
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
37add
38.Op Fl f
39.Ao Pa pkg.txz Ac
40.Nm
41.Fl N
42.Nm
43bootstrap
44.Op Fl f
45.Sh DESCRIPTION
46.Nm
47is the package management tool.
48It is used to manage local packages installed from
49.Xr ports 7
50and install/upgrade packages from remote repositories.
51.Pp
52To avoid backwards incompatibility issues, the actual
53.Xr pkg 8
54tool is not installed in the base system.
55The first time invoked,
56.Nm
57will bootstrap the real
58.Xr pkg 8
59from a remote repository.
60.Bl -tag -width "pkg bootstrap"
61.It Nm Ao Ar command Ac
62If
63.Xr pkg 8
64is not installed yet, it will be fetched, have its signature verified,
65installed, and then have the original command forwarded to it.
66If 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
69Install
70.Xr pkg 8
71from a local package instead of fetching from remote.
72If a
73.Pa pkg.txz.sig
74file exists and
75signature checking is enabled, then the signature will be verified
76before installing the package.
77If the
78.Fl f
79flag is specified, then
80.Xr pkg 8
81will be installed regardless if it is already installed.
82.It Nm Fl N
83Do not bootstrap, just determine if
84.Xr pkg 8
85is actually installed or not.
86Returns 0 and the number of packages installed
87if it is, otherwise 1.
88.It Nm Li bootstrap Op Fl f
89Attempt to bootstrap and do not forward anything to
90.Xr pkg 8
91after it is installed.
92If the
93.Fl f
94flag is specified, then
95.Xr pkg 8
96will be fetched and installed regardless if it is already installed.
97.El
98.Sh CONFIGURATION
99Configuration varies in whether it is in a repository configuration file
100or the global configuration file.
101.Pp
102Repository configuration can be stored in
103.Pa /etc/pkg/FreeBSD.conf
104in the following format:
105.Bd -literal -offset indent
106FreeBSD: {
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
116Refer to
117.Dv PACKAGESITE
118in
119.Sx ENVIRONMENT
120.It mirror_type
121Refer to
122.Dv MIRROR_TYPE
123in
124.Sx ENVIRONMENT
125.It signature_type
126Refer to
127.Dv SIGNATURE_TYPE
128in
129.Sx ENVIRONMENT
130.It fingerprints
131Refer to
132.Dv FINGERPRINTS
133in
134.Sx ENVIRONMENT
135.It enabled
136Defines whether this repository should be used or not.
137Valid values are
138.Dv yes ,
139.Dv true ,
140.Dv 1 ,
141.Dv no ,
142.Dv false ,
143.Dv 0 .
144.El
145.Pp
146Global configuration can be stored in
147.Pa /usr/local/etc/pkg.conf
148in the following format:
149.Bd -literal -offset indent
150PACKAGESITE: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
151MIRROR_TYPE: "srv",
152SIGNATURE_TYPE: "none",
153FINGERPRINTS: "/usr/share/keys/pkg",
154ASSUME_ALWAYS_YES: "yes"
155.Ed
156.Pp
157Reference
158.Sx ENVIRONMENT
159for each variable.
160.Sh ENVIRONMENT
161The following environment variables can be set to override the settings
162from the
163.Pa pkg.conf
164file used.
165.Bl -tag -width "ASSUME_ALWAYS_YES"
166.It Ev MIRROR_TYPE
167This defines which mirror type should be used.
168Valid values are
169.Dv SRV ,
170.Dv HTTP ,
171.Dv NONE .
172.It Ev ABI
173This defines the ABI for the package to be installed.
174Default ABI is determined from
175.Pa /bin/sh .
176.It Ev ASSUME_ALWAYS_YES
177If set, no confirmation will be asked when bootstrapping
178.Xr pkg 8 .
179.It Ev SIGNATURE_TYPE
180If set to
181.Dv FINGERPRINTS
182then a signature will be required and validated against known
183certificate fingerprints when bootstrapping
184.Xr pkg 8 .
185.It Ev FINGERPRINTS
186If
187.Sy SIGNATURE_TYPE
188is set to
189.Dv FINGERPRINTS
190this value should be set to the directory path where known fingerprints are
191located.
192.It Ev PACKAGESITE
193The URL that
194.Xr pkg 8
195and other packages
196will be fetched from.
197.El
198.Sh FILES
199Configuration is read from the files in the listed order.
200The 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
207Some examples are listed here.
208The full list of available commands are available in
209.Xr pkg 8
210once it is bootstrapped.
211.Pp
212Search for a package:
213.Dl $ pkg search perl
214.Pp
215Install a package:
216.Dl % pkg install perl
217.Pp
218List installed packages:
219.Dl $ pkg info
220.Pp
221Upgrade from remote repository:
222.Dl % pkg upgrade
223.Pp
224List non-automatic packages:
225.Dl $ pkg query -e '%a = 0' %o
226.Pp
227List automatic packages:
228.Dl $ pkg query -e '%a = 1' %o
229.Pp
230Delete an installed package:
231.Dl % pkg delete perl
232.Pp
233Remove unneeded dependencies:
234.Dl % pkg autoremove
235.Pp
236Change a package from automatic to non-automatic, which will prevent
237.Ic autoremove
238from removing it:
239.Dl % pkg set -A 0 perl
240.Pp
241Change a package from non-automatic to automatic, which will make
242.Ic autoremove
243allow it be removed once nothing depends on it:
244.Dl % pkg set -A 1 perl
245.Pp
246Create package file from an installed package:
247.Dl % pkg create -o /usr/ports/packages/All perl
248.Pp
249Determine which package installed a file:
250.Dl $ pkg which /usr/local/bin/perl
251.Pp
252Audit installed packages for security advisories:
253.Dl $ pkg audit
254.Pp
255Check installed packages for checksum mismatches:
256.Dl # pkg check -s -a
257.Pp
258Check for missing dependencies:
259.Dl # pkg check -d -a
260.Sh SEE ALSO
261.Xr ports 7 ,
262.Xr pkg 8
263.Sh HISTORY
264The
265.Nm
266command first appeared in
267.Fx 9.1 .
268It became the default package tool in
269.Fx 10.0 ,
270replacing the
271pkg_install suite of tools
272.Xr pkg_add 1 ,
273.Xr pkg_info 1 and
274.Xr pkg_create 1 .
275