PBI Manager/10.1

From PC-BSD Wiki
Revision as of 08:28, 3 June 2014 by Drulavigne (Talk | contribs)

Jump to: navigation, search

PBI Manager is a suite of command line utilities which can be used to install, remove, create and manage PBIs.

This chapter provides an overview of the commands that are installed by PBI Manager. For more details, refer to that command's man page. Note that single character options can not be stacked. As an example, you must type pbi_add -i -v as pbi_add -iv will fail.



The pbi_add command is used for adding/installing PBIs on a system, either from a local file or remotely from a repository. This utility supports the options listed in Table 7.3a. All of the options, except for -r, assume that the .pbi file has already been downloaded and is in the current or specified directory.

Table 7.37.3a: pbi_add Options [Tables 1]
Switch Description
-e extract only, do not install; will extract the archive to ~/<pbidirname> unless the -o option is used
-f force installation, overwriting an already installed copy of the application
-g show path to icons and images for GUI installations
-i display information about specified PBI; if combined with -v, will display all of the files that will be installed with the PBI
-l display license for specified PBI
-o outdir specify the directory to use when extracting the PBI with -e
-r remote fetch installation file from update server; the system version will be automatically determined in order to fetch the correct file and resume support is built-in
-R remote fetch the install file from the update server but do not install
-v enable verbose output
--checkscript display any custom scripts used in the installation/removal of the PBI
--licagree agree to license terms and conditions; to view the license, use -l
--no-checksig skip the openssl signature verification of the PBI data
--no-checksum skip the checksum verification of the archive data
--no-hash disable using the shared hash dir
--repo repoid specify which repository to use
--rArch arch manually specify the PBI architecture type of i386 or amd64
--rVer version specify which version of the PBI to install

For security reasons, it is recommend that users first use the -i -v and --checkscript options to view archive contents and installation scripts prior to installing a PBI file.

To install a PBI from a remote repository, use: pbi_add -r name_of.pbi. The following example will install the alpine PBI:

pbi_add -r alpine

/usr/pbi/.alpine-2.00_4_1-amd64.pbi 100% of 22 MB 159 kBps 02m27s Verifying Checksum...OK Extracting to: /usr/pbi/alpine-amd64

Installed: Alpine-2.00_4_1

PBI Manager will automatically install the appropriate PBI. If only a 32-bit version is available, the 32-bit PBI will be installed and will work correctly on the PC-BSD® system.

If you previously downloaded the PBI, do not include the -r switch and give the fullname of the PBI:

pbi_add alpine-2.00_4_1-amd64.pbi


pbi.conf is an ASCII text configuration file containing values that are used by the various pbi_* commands. The proxy variables are only needed if the system uses a proxy server to access the Internet. Table 7.3d lists the supported variables.

Table 7.37.3d: pbi.conf Variables [Tables 2]
Variable Description
PBID_REFRESH wakeup time in seconds for pbid to run its checks
PBI_INDEXREFRESH number of hours representing how often pbid refreshes the index and meta files from repos; default is every 24 hours
PBI_PROXYURL proxy server IP address
PBI_PROXYPORT proxy server port number
PBI_PROXYUSER username used to authenticate with proxy server
PBI_PROXYPASS password used to authenticate with proxy server
PBI_FBSDMAJOR can be set to the major FreeBSD version when running -CURRENT or some other version with no PBIs


Similar to FreeBSD's pkg_delete, the pbi_delete command removes an installed PBI from the system. It also schedules cleaning for the shared library directory, which is performed by pbid. Table 7.3f summarizes its options:

Table 7.37.3f: pbi_delete Options [Tables 3]
Switch Description
-v enable verbose output
--clean-hdir perform a full cleaning of the shared hash directory, removing any unused files; should only be required after a system crash or failure in removing a PBI

The following example uninstalls the previously installed alpine PBI:

pbi_delete -v alpine-2.00_4_1-amd64

Running pre-removal script: /var/db/pbi/installed/alpine-2.00_4_1-amd64/pre-remove.sh Removing: /usr/pbi/alpine-amd64

Removing: /var/db/pbi/installed/alpine-2.00_4_1-amd64


The pbi_icon command provides a number of options for adding desktop icons, menu entries, and mime data for an installed PBI. Not all PBIs will contain desktop/menu/mime data. Additionally, the window manager must be XDG[1]-compliant to understand a PBI's icon and mime settings. Table 7.3g summarizes this command's options:

Table 7.37.3g: pbi_icon Options [Tables 4]
Switch Description
add-desktop installs desktop icon; should be run as regular user
add-mime installs mime information; should be run as root
add-menu installs menu icons; should be run as root
add-pathlnk installs any $PATH links to ~/bin when run as user or to $LOCALBASE when run as root
del-desktop removes desktop icon; should be run as regular user
del-menu removes menu icons; should be run as root
del-mime removes mime information; should be run as root
del-pathlnk removes any $PATH links to ~/bin when run as user or to $LOCALBASE when run as root


Similar to FreeBSD's pkg_info command, the pbi_info command is used to determine which PBIs are currently installed. Table 7.3i summarizes the available options:

Table 7.37.3i: pbi_info Options [Tables 5]
Switch Description
-a list all PBIs installed on the system; same as running pbi_info without an argument
-i list all available PBIs from any repo
-v enable verbose output


The pbi_listrepo command manages installed repositories on a system. Table 7.3j summarizes this command's options:

Table 7.37.3j: pbi_listrepo Options [Tables 6]
Switch Description
--down move the targeted repoID down a single number in priority
-mirror URL change the specified repoID's mirror URL
--up move the targeted repoID up a single number in priority

Run the command without any options to list the IDs of the available repositories.


The pbi_makepatch command is automatically used by pbi_autobuild to create small *.pbp (Push Button Patch) files. These files can be downloaded to a user's system in order to update a PBI's version without re-downloading the entire archive. This allows users to download only the incremental changes when a PBI is upgraded. The command can also be run manually by providing two PBI archives to compare and generate a patch file for.

Table 7.3k summarizes the available options:

Table 7.37.3k: pbi_makepatch Options [Tables 7]
Switch Description
-o outdir save the resulting *pbp file to the specified directory
--sign keyfile use the specified openssl key to digitally sign the patch file
--tmpfs can reduce building time for large PBIs


The pbi_makeport command can be used by packagers to build a target FreeBSD port and convert it into a PBI file. Many options are provided to fine-tune the build process, and meta-data modules can also be specified to further improve the resulting PBI file. The first time this command is run, it will build a fresh chroot sandbox environment which can be used for clean-room building of the target port without affecting the host system. More details about how to create a PBI using this command, can be found in the PBI Module Builder Guide.

NOTE: The pbi_makeport command has support for using ccache[2] to speed up the compile process. If ccache is installed on the host system and the CCACHE_DIR variable is set, the pbi_makeport command will automatically utilize it for the port compile phase. This can be disabled by setting NO_CCACHE=yes in /etc/pbi-make.conf on the host system, or as an optional make flag in a module's pbi.conf file.

pbi_makeport, will attempt to create any users or groups that the underlying ports require during the PBI installation. If the PBI is being installed as non-root, it will instead provide a warning message regarding any users or groups that need to be manually created. For this functionality to work, the port must set USERS= or GROUPS= in its Makefile and provide the corresponding UID and/or GID entries.

Table 7.3l summarizes the available options:

Table 7.37.3l: pbi_makeport Options [Tables 8]
Switch Description
-B build-only; generally used with -k to build a port before running pbi_create manually
-c confdir specify the metadata configuration directory; while not required it is highly recommended as metadata is required to create icons and binary entry-points
-d portsdir specify an alternative ports directory; defaults to /usr/ports
-k keep the build files after building the PBI
-o outdir the directory to place the finished PBI file; defaults to user's $HOME directory
-p prefix manually provide a PREFIX which determines the location where the PBI will be installed on the end-user's system
--32 include when building a 32-bit PBI on a 64-bit system
--delbuild remove any existing build directories before starting the build
--mkdebug will drop to a debugging shell should the port make fail
--no-prune disable auto-pruning of non-REQUIREDBY ports after the compile phase; by default any ports which are used solely for building and which are not required for program execution will be pruned
--pkgdir dir uses the specified directory to cache the .txz package so subsequent builds will not rebuild the port from source
--tmpfs automatically create and mount a tmp filesystem and use it for WRKDIRPREFIX; can speed up port compiles on systems with available RAM
--sign keyfile digitally sign the PBI file with the specified openssl private key file


The pbi_makerepo command allows repository maintainers to create a single *.rpo file containing various information about the new repository. This .rpo file can then be installed on the target system with pbi_addrepo. Table 7.3m summarizes the available options.

Table 7.37.3m: pbi_makerepo Options [Tables 9]
Switch Description
--desc description required; description of the repo to be shown in the repo list
--key keyfile required; OpenSSL public key used to verify the digital signature of PBIs installed from this repo
--mirror URL required; URL in http://, https://, or ftp:// format to download PBIs and updates from
--url URL required; URL in http://, https://, or ftp:// format to use when downloading the master INDEX file of available PBIs


The pbi_metatool command provides a way for repository maintainers to modify the PBI metadata in their repository in order to add or remove application categories or specified PBIs. An example of using this command can be found in Create Your Own PBI Repository. Table 7.3n summarizes the available options:

Table 7.37.3n: pbi_metatool Options [Tables 10]
Command Switch Description
add or rem --cat indicates that a new category is being added to or removed from the target metafile
--app adds or removes a new PBI to/from the target metafile
add -a author adds the name of the application's author to the target metafile
-c category name of new category to add to the target metafile
-d desc mandatory description of PBI or category being added
-i icon mandatory URL to 64x64 .png icon of PBI or category being added
-k keywords comma delimited list (with no spaces) of search keywords
-l license type of license (e.g. BSD, GPL, Commercial)
-m email address of application/port maintainer
add or rem -n name mandatory name of category or PBI being added to or removed from the target metafile
add -t type type of application (e.g. Graphical, Text, Service)
-u URL website of application being added
-r include if application needs to be installed as the superuser
add -s shortdesc short description of application


The pbi_patch command is used to update an installed PBI to a different version using a small diff Push Button Patch *.pbp file. This allows the user to perform an incremental upgrade of an installed PBI. The available options are summarized in Table 7.3o.

Table 7.37.3o: pbi_patch Options [Tables 11]
Switch Description
-e extract only, do not install; will extract the archive to ~/<pbidirname> unless -o is used.
-g extract image data from header; commonly used for GUI installations
-i display information about this PBI file
-o outdir specify the directory to use when only extracting the PBI with -e
--checkscript display any custom scripts used in the installation/removal of this PBI file; recommended if the PBI file is suspect in any way
--no-checksig skip the openssl signature verification of the PBI data
--no-hash disable using the shared hash directory which uses hard links to share files between applications


The pbi_update command is used to display information about which PBIs have available updates and to perform the updates. Table 7.3p summarizes the available options.

Table 7.37.3p: pbi_update Options [Tables 12]
Switch Description
-c check only the specified PBI for available updates
--check-all run a full check of all installed PBIs and display list of available updates
-disable-auto disable auto-updating of the target PBI
--enable-auto enable auto-updating of the target PBI
--update-all update all installed PBIs to the latest versions


The pbi_update_hashdir command is used by the pbid daemon to merge the contents of a PBI into the hash directory.


The pbid command runs a small daemon which performs maintenance of installed PBIs, merges files into the shared hashdir, fetches the repository INDEX and meta files, and makes the adding and removing of PBIs much faster. It will automatically be started from the/usr/local/etc/rc.d/pbid startup script if pbid_enable="YES" is in the /etc/rc.conf file.

This utility supports the option summarized in table 7.3q:

Table 7.37.3q: pbid Options [Tables 13]
Switch Description
-v enable verbose output when the daemon starts
--refresh schedule a refresh of index and meta files

This command logs its output to /var/log/pbid.log. Check this log for errors should you experience any problems with PBI maintenance.


  1. http://en.wikipedia.org/wiki/Xdg
  2. http://ccache.samba.org/

 Translator:  Please update the last element on this page, and/or locate the {{groupListHeading|group=tables}} line, replace that with {{GroupRefHeading|{{putCommon|19}}}}

Other languages:German 11% • ‎English 100%

Cite error: <ref> tags exist for a group named "Tables", but no corresponding <references group="Tables"/> tag was found
Personal tools