System Administration Commandspkg.depotd(1M)NAMEpkg.depotd - image packaging system depot server
SYNOPSIS
/usr/lib/pkg.depotd [-d inst_root] [-p port] [-s threads]
[-t socket_timeout] [--add-content] [--cfg] [--content-root]
[--debug] [--disable-ops=<op[/1]>[,...]] [--log-access]
[--log-errors] [--mirror] [--proxy-base url] [--readonly]
[--rebuild] [--ssl-cert-file] [--ssl-dialog] [--ssl-key-file]
[--writable-root]
DESCRIPTIONpkg.depotd is the depot server for the image packaging system.
It provides network access to the data contained within a package
repository. Clients that do not support direct access to a
repository through the filesystem, or are in situations where
networkaccess may be the only available or preferred method of
transport typically use the package depot.
Clients such as pkg(1), the retrieval client, can retrieve a list
of packages and package metadata from a repository directly or
through the depot server. pkgsend(1), the publication client,
can send new versions of packages to a repository directly or
through the depot server. pkgrepo(1) can be used to create
repositories for use with the depot server, or to manage them
both directly and through the depot server. See the man pages
of each program for more information about supported operations.
pkg.depotd is typically run as a service on the system. Package
and software developers may wish to run private copies for
testing.
The depot currently does not provide any access control methods
of its own. By default, all of the clients that are able to
connect are able to read all package data and publish new
package versions (with the exception that when running under SMF,
the default is to run in read-only mode). The NOTES section
below describes some best practices for maintaining a public
depot server with evolving content.
The pkg.depot server is generally configured via the smf(5)
properties associated with its service. The following
properties are recognized:
pkg/content_root (astring) The file system path at
which
the instance should find its static
and other web content. The default
value is /usr/share/lib/pkg.
pkg/debug (astring) A comma-separated list of
debug features to enable. Possible
values are:
headers
Logs the headers of every
request to the error log.
pkg/disable_ops (astring) A comma-separated list of
operations that should be disabled for
the depot server. Operations are
given as <operation>[/<version>]
(e.g. catalog, search_1).
pkg/file_root (astring) The root of the file content
for this repository. If undefined,
this defaults to <inst_root>/file.
pkg/inst_root (astring) The file system path at
which the instance should find its
repository data. Required unless
file_root or PKG_REPO has been
provided. The default value is
/var/pkg/repo.
pkg/log_access (astring) The destination for any
access related information logged by
the depot process. Possible values
are: stderr, stdout, none, or an
absolute pathname. The default value
is stdout if stdout is a tty; if it
is not a tty, the default value is
none.
pkg/log_errors (astring) The destination for any
errors or other information logged by
the depot process. Possible values
are: stderr, stdout, none, or an
absolute pathname. The default value
is stderr.
pkg/mirror (boolean) Sets whether package mirror
mode is used. When true, publishing
and metadata operations are disabled
and only a limited browser user
interface is provided. This property
may not be true when the pkg/readonly
property is true. The default value
is false.
pkg/port (count) The port number on which the
instance should listen for incoming
package requests. The default value
is 80 if ssl certificate and key
information has not been provided;
otherwise, the default value is 443.
pkg/proxy_base (uri) This changes the base URL for
the depot server and is most useful
when running behind Apache or some
other webserver in a reverse proxy
configuration.
pkg/readonly (boolean) Sets whether modifying
operations, such as those initiated
by pkgsend(1M) are disabled. Retrieval
operations are still available. This
property may not be true when the
pkg/mirror property is true. The
default value is true.
pkg/socket_timeout (count) The maximum number of seconds
the server should wait for a response
from a client before closing a conn-
ection. The default value is 60.
pkg/sort_file_max_size (count) The maximum size of the
indexer sort file. Used to limit the
amount of RAM the depot uses for
indexing, or increase it for speed.
pkg/ssl_cert_file (astring) The absolute pathname to a
PEM-encoded Certificate file. The
default value is none. This property
must be used with ssl_key_file. The
depot will only respond to SSL
requests if provided.
pkg/ssl_dialog (astring) Specifies what method should
be used to obtain the passphrase used
to decrypt the ssl_key_file. Possible
values are: exec:/path/to/program,
builtin, or smf:fmri. builtin will
prompt for the passphrase; exec will
execute the specified external program
to obtain the passphrase, which should
be printed to stdout. The first
argument to the program will be '',
and is reserved. The second argument
to the program will be the port number
of the server. smf:fmri will attempt
to retrieve the value of the property
pkg_secure/ssl_key_passphrase from the
service instance related to the fmri.
The default value is builtin.
pkg/ssl_key_file (astring) The absolute pathname to a
PEM-encoded Private Key file. This
property must be used with the
property ssl_cert_file. The depot
will only respond to SSL requests if
provided.
pkg/threads (count) The number of threads that
will be started to serve requests.
The default value is 10.
pkg/writable_root (astring) The file system path to a
directory to which the program has
write access. This is used with
--readonly to allow the depot server
to create files, such as search
indices, without needing write
access to the package information.
pkg_secure/ssl_key_passphrase (astring) The password to use to
decrypt the pkg/ssl_key_file.
This value is read-authorization
protected using the attribute
'solaris.smf.read.pkg-server'.
The presentation and behavior of the Browser User Interface
(BUI) of the depot server is controlled using the following
properties:
pkg_bui/feed_description (astring) A descriptive paragraph
for the RSS/Atom feed.
pkg_bui/feed_icon (astring) The pathname of a small
image that will be used to visually
represent the RSS/Atom feed. The
pathname should be relative to the
content_root. The default value is
"web/_themes/pkg-block-icon.png"
pkg_bui/feed_logo (astring) The pathname of a large
image that will be used to visually
brand or identify the RSS/Atom feed.
This value should be relative to the
content_root. The default value is
"web/_themes/pkg-block-icon.png".
pkg_bui/feed_name (astring) A short, descriptive name
for RSS/Atom feeds generated by the
depot serving the repository. The
default value is "package repository
feed".
pkg_bui/feed_window (count) A numeric value representing
the number of hours, before the feed
for the repository was last generated,
to include when generating the feed.
The pkg depot is also able to act as a mirror server for local
client images from pkg(5). This allows clients that share a
subnet on a LAN to mirror their file caches. Clients may
download files from one another, thereby reducing load on the
package depot server. This functionality is available as an
alternate depot service configured by smf(5). It uses mDNS and
dns-sd for service discovery.
The mDNS mirror is generally configured via the smf(5) properties
associated with its service. The following properties are
recognized:
pkg/file_root (astring) The file system path at which the
instance should find its file content. The
default value is /var/pkg/download.
pkg/port (count) The port number on which the instance
should listen for incoming package requests.
The default value is 80.
OPTIONSpkg.depotd(1m) can read its base configuration information from
a file or from the property data of an existing smf(5) service
instance:
--cfg source The pathname of the file to use when reading and
writing configuration data, or a string of the
form 'smf:fmri' where fmri is the service fault
management resource identifier (FMRI) of the
instance to read configuration data from. See
DEPOT CONFIGURATION below for details on the
format of the file specified.
If no pre-existing configuration source is available, or to
override values read from a provided configuration file using
'--cfg', the following options can be used to alter the default
behavior of the depot server:
-d inst_root See pkg/inst_root above.
-p port See pkg/port above.
-s threads See pkg/threads above.
-t socket_timeout See pkg/socket_timeout above.
--content-root root_dir See pkg/content_root above.
--disable-ops op_list See pkg/disable_ops above.
--debug features See pkg/debug above.
--file-root path See pkg/file_root above.
--log-access dest See pkg/log_access above.
--log-errors dest See pkg/log_errors above.
--mirror See pkg/mirror above.
--proxy-base url See pkg/proxy_base above; ignored if
empty value is provided.
--readonly See pkg/readonly above.
--sort-file-max-size bytes See pkg/sort_file_max_size above.
--ssl-cert-file source See pkg/ssl_cert_file above.
--ssl-dialog type See pkg/ssl_dialog above.
--ssl-key-file source See pkg/ssl_key_file above.
--writable-root path See pkg/writable_root above.
Additional administrative and management functionality for
package repositories is provided by pkgrepo(1).
DEPOT CONFIGURATION
When a configuration file is provided (instead of an smf(5) FMRI)
using the --cfg option, the depot server will read and write all
configuration data (listed in DESRIPTION above) in a simple text
format that consists of sections, lead by a "[section]" header,
and followed by "name = value" entries, with continuations, etc.
in the style of RFC 822. Values can be split over multiple lines
by beginning continuation lines with whitespace.
Any required values not provided in the configuration file must
be provided using the option listed in OPTIONS above. A sample
configuration file might look like this:
[pkg]
port = 80
inst_root = /var/pkg/repo
[pub_example_com]
feed_description = example.com's software
update log
EXAMPLES
Example 1: Enabling the depot server.
# svcadm enable application/pkg/server
Example 2: Changing the listening port of the server.
# svccfg -s application/pkg/server setprop pkg/port = 10000
# svcadm refresh application/pkg/server
# svcadm restart application/pkg/server
Example 3: Enabling the mirror.
# svcadm enable application/pkg/dynamic-mirror
Example 4: Changing the listening port of the server.
# svccfg -s application/pkg/server setprop pkg/port = 20000
# svcadm refresh application/pkg/server
# svcadm restart application/pkg/server
ENVIRONMENT VARIABLES
PKG_REPO Specifies the directory containing the
repository to server. This will be
ignored if -d was used.
PKG_DEPOT_CONTENT Specifies the directory containing
static content served by the depot.
The files listed below under FILES
should be present in this directory,
although their content may differ
from the supplied default content.
EXIT STATUS
The following exit values are returned:
0 Successful operation.
1 Error encountered.
2 Invalid command line options were specified.
FILES
/var/pkg/repo Default repository location; modify
pkg/inst_root to select an
alternate location.
/usr/share/lib/pkg Default presentation content location;
modify pkg/content_root to select an
alternate location.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWipkg |
| | pkg:/package/pkg |
|_____________________________|_____________________________|
| Interface Stability | None / Under Development |
|_____________________________|_____________________________|
SEE ALSOdns-sd(1), mdnsd(1), pkg(1), pkgrepo(1), pkgsend(1), syslogd(1M),
attributes(5), smf(5)NOTES
The image packaging system is an under-development feature.
Command names, invocation, formats, and operations are all
subject to change. Development is hosted in the OpenSolaris
community at:
http://hub.opensolaris.org/bin/view/Project+pkg/
The pkd.depotd service is managed by the service management
facility, smf(5), under the service identifier:
svc:/application/pkg/server
The mDNS mirror service is managed by the service management
facility, smf(5), under the service identifier:
svc:/application/pkg/dynamic-mirror
Because the depot server and mirror expect to be run by an smf(5)
restarter, they do not daemonize. Error messages are generally
sent to standard output, or to the syslogd(1M) system.
When publishing individual package files that are greater than
128MB in size, filesystem-based publication must be used due to
publication protocol limitations. See pkgsend(1) for more
information.
For controlling read access to the depot, it is suggested that
administrators use an HTTP reverse proxy in combination with
authentication methods such as client-based SSL certificate
access which pkg(1) natively supports.
If new package versions must be added to a public depot, it is
suggested that filesystem-based publication be performed instead,
and that the depot server process be restarted afterwards. For
more information about filesystem-based publication, see
pkgsend(1).
Changes to configuration, or changes to package data using file-
system based operations require a restart of the depot server
process so that they can be reflected in operations and output.
This can be done by using one of the following methods:
* using svcadm(1M) to restart the application/pkg/server
instance
* sending a SIGUSR1 signal to the depot server process using
kill(1), which will execute a 'graceful restart' that leaves
the process intact, but reloads all configuration, package,
and search data:
kill -USR1 <pid>
