Create Your Own PBI Repository/9.2

From PC-BSD Wiki
Revision as of 07:53, 30 October 2012 by Drulavigne (Talk | contribs)

Jump to: navigation, search

(Sorry for the inconvenience)


By default, AppCafe® displays the PBIs which are available from the official PC-BSD® repository. It also supports custom repositories, allowing organizations to create PBIs for their own applications and to make them available to their users within AppCafe®.

In order to create a custom repository, you need to:

  • create the OpenSSL signing key which will be used to sign custom PBIs
  • generate a repository file and populate it with custom PBIs
  • generate the meta-data for the PBIs which are available within the repository

This section describes these steps in more detail.

Generate the Signing Key

Running a repository requires that all the PBIs in the custom repository be digitally signed for security and identification purposes. In order to sign the PBIs, generate an OpenSSL key pair using the following commands:

openssl genra -out privkey.pem 4096
Generating RSA private key, 4096 bit long modulus
e is 65537 (0x10001)
openssl rsa -in privkey.pem -pubout > pub.key
writing RSA key

These commands will create the files privkey.pem and pub.key. The privkey.pem file will be used to digitally sign your created PBI files and the pub.key file will be included with the repository configuration (.rpo) file.

Create the Repository

In order to create the repository you will need a FTP, HTTP, or HTTPS server to host your repository’s meta-data files and to store the repository's PBIs. The server can be a public URL on the Internet or a private LAN server, as long as it is accessible to your target audience.

Once you have the URL to the server, create the repository's .rpo file using the pbi_makerepo command. Replace the values in the following example with your own description, path to your generated pub.key file, the URL to the location where the PBIs will be hosted, the URL to the location to contain the repository's meta-data files, and the directory to place the created .rpo file.

pbi_makerepo --desc “My Example Repository”  --key pub.key --mirror “” --url “” /root

This command will generate the pbi-repo.rpo file in the specified directory on the server. This file is needed for clients to register with and begin using the new repository. Instruct your clients to download this file to their PC-BSD® desktop, then to configure their system to use the repository using this command as the superuser:

pbi_addrepo pbi-repo.rpo

Once the repository is registered on the clients system, their pbi daemon will automatically keep track of downloading and updating both meta-files and PBIs from the URLs you specified in the repository configuration file.

Generate the Repository's Meta-Data

On a PC-BSD® system, you can now create the meta-data and PBI files so that clients have something to download. The meta-data file is used to give the client information about the PBIs available from the repository, such as categories, application names, and descriptions. When creating categories, you can use the same category names that appear in AppCafe®, or you can create your own categories. Each category and each PBI will need its own icon. These icons need to exist on the server before generating the meta-data file.

When you are ready, create an empty meta-data file in the format pbi-meta-<Major Version Number>. This command should be used for 9.x series PBIs:

touch pbi-meta-9

Then use the pbi_metatool command to add the category for a PBI. The following command adds the "Archivers" category, its description, and the URL pointing to the mandatory 64x64 .png icon file to the specified meta-data file.

pbi_metatool add --cat -n “Archivers” -d “File Archivers and Utilities” -i “” pbi-meta-9

Next, add the following information about the PBI: the name of the application, the category, the application author, a description of the application, the URL pointing to the mandatory 64x64 .png icon file for the application, a comma delimited list (with no spaces) of search keywords, the type of license, the type of application ("Graphical", "Text", or "Service"), the URL to the application's website, and the name of the meta-data file to add the information to.

pbi_metatool add --app -n “cabextract” -c “Archivers” -a “Stuart Caie” -d “Utility for reading and extracting .cab files.” -i '''' -k “cab,archive,extract” -l “LGPL” -t “Text” -u “” pbi-meta-9

Repeat this command for each PBI that will be available in the repository, creating new categories as you need to do so.

When you are finished adding the information for the repository's PBIs, compress the file with bzip2 and upload it to the server. The location in our example would be Once the file is uploaded, clients can use the pbi_browser command or AppCafe® to browse the repository's PBIs.

You should now create your custom PBIs then upload them to their specified category in the download directory on the server. In our example, the download directory is Refer to the section on creating PBIs for instructions on creating PBIs using either the EasyPBI graphical utility or the pbi_makeport command line utility.

When creating your PBIs, remember to sign them with the private key. If you are using EasyPBI, specify the location to the privkey.pem file by clicking the "Change File" button shown in Figure 8.1d. If you are using the pbi_makeport command, include --sign privkey.pem in the command.

Lastly, create the pbi-index-9 file and add the names of the uploaded PBIs to the file. Use the pbi_indextool to add each entry, specifying that PBI's filename (will end in .pbi), the download location (in the format category/pbi_name), and the name of the index file.

touch pbi-index-9
pbi_indextool -f cabextract-1.2-amd64.pbi -u “archivers/cabextract-1.2-amd64.pbi” pbi-index-9

When you are finished adding entries to this file, use bzip2 to compress it and upload the pbi-index-9.bz2 to the same location on the server where the pbi-meta-9.bz2 file is stored. Clients can now download and install PBIs from your custom repository, using the pbi_add command or AppCafe®.

Configure the Automatic Build of Updated Ports

Over time, the PBIs in your repository will become out-of-date as the versions of the underlying ports change. You can automate the process of automatically rebuilding the newer version of a PBI, as well as generating the binary diff changes to the PBI (which users use to upgrade their installed version of the PBI), whenever an underlying port changes.

To configure this scenario, ensure that all of your PBI modules exist under the same directory and follow the directory structure of the ports tree. For example, if you have created PBIs for cabextract and firefox, the subdirectory structure for /usr/local/my_pbis/ would be archivers/cabextract/ and www/firefox/.

To start the build process, use the pbi_autobuild command as seen in this example:

pbi_autobuild --keep 2 -c /usr/local/my_pbis -o /usr/local/my_pbis --prune --tmpfs --sign /root/privkey.pem –genpatch

This command keeps the last 2 versions of the PBI, reads the modules located in the subdirectories of /usr/local/my_pbis, places the built PBIs in the /usr/local/my_pbis directory, removes any PBIs which no longer have an associated module, uses tmpfs to optimize build speed, signs the PBIs with the specified key, and generates the .pbp patch files needed by users to upgrade an installed version of the previous PBI. The new PBIs and .pbp files will be placed in the specified outgoing directory. If an earlier version of the PBI exists in that directory, it will be placed into the archived subdirectory.

If /devel/ccache is installed on the build system and the CCACHE_DIR variable is set, pbi_autobuild will detect and use it which can greatly speed up the process of building the PBIs.

Depending upon the load on the build server and how many PBIs are affected by the build, you may wish to modify some pbi.conf values in particular PBI modules. The variables that can affect a build are:

  • PBI_BUILDKEY: set to a numerical value to instruct pbi_autobuild to rebuild that particular PBI. This is useful when a port has failed to build or you wish to rebuild a PBI with new compile options even though the upstream target port has not changed.
  • PBI_AB_PRIORITY: when automatically building a large number of PBIs, the build process occurs alphabetically. By setting an incremental integer value, it is possible to artificially force the building of PBIs in the specified order of importance.
  • PBI_AB_NOTMPFS: typically, using the --tmpfs flag greatly speeds up the build process by extracting a port's files into memory, and compiling directly into RAM. However some ports, such as OpenOffice, require more memory than is available, causing the build to fail. By setting this variable to YES in that PBI's pbi.conf, it is possible to flag that port as needing to build in the traditional manner from disk.
  • PBI_MAKEOPTS: if you use ccache, you may occasionally run into a port that will not compile properly with CCACHE enabled. For that PBI, edit this variable to include NO_CCACHE=yes which will disable CCACHE for that specific port build.