pkg.depotd - Image Packaging System depot server
/usr/lib/pkg.depotd [--cfg source] [-a address] [--content-root root_dir] [-d inst_root] [--debug feature_list] [--disable-ops=op[/1][,...]] [--image-root path] [--log-access dest] [--log-errors dest] [--mirror mode] [-p port] [--proxy-base url] [--readonly mode] [-s threads] [--sort-file-max-size bytes] [--ssl-cert-file source] [--ssl-dialog type] [--ssl-key-file source] [-t socket_timeout] [--writable-root path]
pkg.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 file system, or for which network access is the only available or preferred method of transport, typically use the package depot.
Clients such as pkg, the retrieval client, can retrieve a list of packages and package metadata from a repository directly or through the depot server. pkgsend, the publication client, can send new versions of packages to a repository directly or through the depot server. pkgrepo can be used to create repositories for use with the depot server, or to manage them both directly and through the depot server.
pkg.depotd is typically run as a service on the system. Package and software developers might want to run private copies for testing.
The depot 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. The exception is that when running under Service Management Facility (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.depotd server is generally configured via the SMF properties associated with its service. The svc:/application/pkg/server service runs a pkg.depot server process, or contributes configuration to the svc:/application/pkg/depot service. See the pkg.depot-config(1M) man page and the pkg/standalone property below.
See the smf(5) man page for information about SMF properties. The following properties are recognized:
(net_address) The IP address on which to listen for connections. The default value is 0.0.0.0 (INADDR_ANY), which listens on all active interfaces. To listen on all active IPv6 interfaces, use ::. Only the first value is used.
(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.
(astring) A comma-separated list of debug features to enable. Possible values are:
Logs the headers of every request to the error log.
(astring) A comma-separated list of operations that should be disabled for the depot server. Operations are given as operation[/version] (catalog or search_1, for example).
(astring) The path to the image whose file information will be used as a cache for file data.
(astring) The file system path at which the instance should find its repository data. Required unless PKG_REPO has been provided. The default value is /var/pkgrepo.
(astring) The destination for any access related information logged by the depot process. Possible values are: stderr, stdout, none, or an absolute path name. The default value is stdout if stdout is a tty. If stdout is not a tty, the default value is none. If you run pkg as a service, the default value for log_access is none and output is written to /var/svc/log/application-pkg-server:*. See the logadm(1M) man page for examples of managing large log files.
(astring) The destination for any errors or other information logged by the depot process. Possible values are: stderr, stdout, none, or an absolute path name. The default value is stderr. See the logadm(1M) man page for examples of managing large log files.
(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 cannot be true when the pkg/readonly property is true. The default value is false.
(count) The port number on which the instance should listen for incoming package requests. If SSL certificate and key information has not been provided, the default value is 80; otherwise, the default value is 443.
(uri) This changes the base URL for the depot server and is most useful when running behind Apache or some other web server in a reverse proxy configuration.
(boolean) Sets whether modifying operations, such as those initiated by pkgsend, are disabled. Retrieval operations are still available. This property cannot be true when the pkg/mirror property is true. The default value is true.
(count) The maximum number of seconds the server should wait for a response from a client before closing a connection. The default value is 60.
(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.
(astring) The absolute path name to a PEM-encoded Certificate file. The default value is none. This property must be used with ssl_key_file. The depot only responds to SSL requests if both ssl_cert_file and /ssl_key_file are provided.
(astring) Specifies what method should be used to obtain the passphrase used to decrypt the ssl_key_file. Possible values are:
Prompt for the passphrase. This is the default value.
Execute the specified external program to obtain the passphrase. The first argument to the program is '', and is reserved. The second argument to the program is the port number of the server. The passphrase is printed to stdout.
Attempt to retrieve the value of the property pkg_secure/ssl_key_passphrase from the service instance related to the FMRI.
(astring) The absolute path name to a PEM-encoded Private Key file. This property must be used with the property ssl_cert_file . The depot only responds to SSL requests if both /ssl_key_file and ssl_cert_file are provided.
(boolean) To easily serve multiple repositories from a single Apache instance with minimal Apache configuration, set this property to false and set the pkg/readonly property of this pkg/server instance to true. The default value of pkg/standalone is false and the default value of pkg/readonly is true. See the pkg.depot-config(1M) man page for more information.
(count) The number of threads started to serve requests. The default value is 60. Suitable only for small deployments. This value should be approximately 20 times the number of concurrent clients. The maximum value of threads is 5000.
(astring) The file system path to a directory to which the program has write access. This is used with the –readonly option to enable the depot server to create files, such as search indexes, without needing write access to the package information.
(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:
(astring) A descriptive paragraph for the RSS/Atom feed.
(astring) The path name of a small image used to visually represent the RSS/Atom feed. The path name should be relative to the content_root. The default value is web/_themes/pkg-block-icon.png .
(astring) The path name 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.
(astring) A short, descriptive name for RSS/Atom feeds generated by the depot serving the repository. The default value is “package repository feed”.
(count) The number of hours before the feed for the repository was last generated, to include when generating the feed.
The package depot is also able to act as a mirror server for local client images from pkg(5). This enables clients that share a subnet on a LAN to mirror their file caches. Clients can 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. It uses mDNS and dns-sd for service discovery.
The mDNS mirror is generally configured via the SMF properties associated with its service. The following properties are recognized:
(astring) The path to the image whose file information will be used as a cache for file data. The default value is /.
(count) The port number on which the instance should listen for incoming package requests. The default value is 80.
pkg.depotd can read its base configuration information from a file or from the property data of an existing SMF service instance.
Specify the path name of a 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 preexisting configuration source is available, or to override values read from a configuration file provided using –-cfg, the following options can be used to alter the default behavior of the depot server:
See pkg/address above.
See pkg/content_root above.
See pkg/inst_root above.
See pkg/debug above.
See pkg/disable_ops above.
See pkg/image_root above.
See pkg/log_access above.
See pkg/log_errors above.
See pkg/mirror above.
See pkg/port above.
See pkg/proxy_base above. This option is ignored if an empty value is provided.
See pkg/readonly above.
See pkg/threads above.
See pkg/sort_file_max_size above.
See pkg/ssl_cert_file above.
See pkg/ssl_dialog above.
See pkg/ssl_key_file above.
See pkg/socket_timeout above.
See pkg/writable_root above.
Display a usage message.
Additional administrative and management functionality for package repositories is provided by pkgrepo.
When a configuration file is provided (instead of an SMF FMRI) by using the –-cfg option, the depot server reads and writes all configuration data in a simple text format. The configuration data is described in “SMF Properties” above. The configuration data consists of sections, lead by a [section] header, and followed by name = value entries. Continuations are 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 = /export/repo [pub_example_com] feed_description = example.com's software update log
# svcadm enable application/pkg/serverExample 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/serverExample 3 Enabling the Mirror
# svcadm enable application/pkg/dynamic-mirror
Specifies the directory that contains the repository to serve. This value is ignored if –d is specified.
Specifies the directory that contains static content served by the depot. The files listed below under “Files” should be present in this directory, although their content can differ from the supplied default content.
The following exit values are returned:
An error occurred.
Invalid command line options were specified.
An unanticipated exception occurred.
Default presentation content location. Modify pkg/content_root to select an alternate location.
See attributes(5) for descriptions of the following attributes:
The pkd.depotd service is managed by SMF under the service identifier svc:/application/pkg/server.
The mDNS mirror service is managed by SMF under the service identifier svc:/application/pkg/dynamic-mirror.
To control read access to the depot, you can use an HTTP reverse proxy in combination with authentication methods such as client based SSL certificate access, which pkg natively supports.
To easily serve multiple repositories from a single Apache instance with minimal Apache configuration, set the pkg/standalone property of a particular pkg/server instance to false and set the pkg/readonly property of that instance to true. See the pkg.depot-config(1M) man page for more information.
Changes to configuration, or changes to package data using file system based operations, require a restart of the depot server process so that the changes can be reflected in operations and output. Use one of the following methods to restart the depot server process:
Use svcadm to restart the application/pkg/server instance.
Send a SIGUSR1 signal to the depot server process using kill. This executes a “graceful restart” that leaves the process intact but reloads all configuration, package, and search data:
# kill -USR1 pid