From PC-BSD Wiki
Revision as of 06:26, 4 June 2014 by Drulavigne (Talk | contribs)

Jump to: navigation, search

AppCafe® provides an intuitive, graphical method for installing, managing, and upgrading PBIs and packages. AppCafe® does not require the root password to install software. This means that you do not have to give out the root password on multi-user systems. However, it will prompt for the user's password and will fail if that user is not a member of the wheel group. This allows you to control which users are able to manage software.

If you prefer to manage PBIs from the command line, see the section on using the PBI Manager suite of command line utilities. Refer to Using the CLI pkg Utilities for instructions on managing packages from the command line.


Finding and Installing and Software

To manage software, start AppCafe® by double-clicking its icon on the Desktop, going to Control Panel → AppCafe®, or by typing pc-su pc-softwaremanager from a command prompt. When prompted, input your password. As seen in Figure 7.1a, AppCafe® will open into the “Browse for Apps” tab.

In the example shown in Figure 7.1a, 1,274 PBIs and 23,339 packages are currently available. This tab provides several buttons and panes:

Figure 7.1a: Browsing Software Using AppCafe®
  • Home button: click this button to return back to this initial screen.
  • Browse Categories button: click this button to access a list of software categories. Click on the name of a software category to browse for its available software.
  • Search bar/button: if you know the name of the application you would like to install, type its name into the “Search Here” bar and either press enter or click the search (binoculars) button.
  • Application Spotlight pane: software the PC-BSD® team recommends as being notable for their software category.
  • PC-BSD Recommendations pane: a list of essential applications for new users.
  • New pane: software which has been recently added to the AppCafe®.

In the example shown in Figure 7.1b, the user searched for the “gimp” application, then clicked the search result.

Figure 7.1b: Browsing the Information Available for a PBI

The following information is available for each application. Note that the rating and tips information is interactive, allowing users to share their tips with other PC-BSD® users. In order to do so, first create a wiki account at the [wiki.pcbsd.orgtxt=PC-BSD® wiki txt=Missing Link][1], click on the activation email for the account, and login.

  • The software category for the application. In this case, “Gimp” is in the “Graphics” category.
  • Name and icon of the application.
  • A hyperlink to the application's website. In this example, clicking "GIMP Team" will open in the user's default web browser.
  • A rating of up to five stars. Click the stars to open the PC-BSD® wiki page for the application. If you login to the wiki and hover the mouse over the number of stars to select, it will add your ranking and increment the vote number. If you make a mistake in your vote, simply click the “remove” button and re-select the desired number of stars.
  • A “User Tips” link. Click the link to open the PC-BSD® wiki page for the application. If you login to the wiki, you can add your own usage tips for the application.
  • An "Install Now!" icon. If the application is already installed, this will either be an "Upgrade" icon (if a newer version is available) or a "Downgrade" button (if the previous version is available).
  • The version of the application.
  • The download size.
  • The platform (i386 for 32-bit applications and amd64 for 64-bit applications). If the application only provides a 32-bit version, AppCafe® will install the 32-bit application and PC-BSD® will still be able to run the program.
  • The license used by the software.
  • The type will indicate whether the application is graphical or text (command line).

The following tabs are also available. If a tab is greyed out, it means that that information is not currently available for this particular application.

  • Description: of the software.
  • Screenshots: click the “View Full Size” button under the screenshot to view the full screen version of the screenshot.
  • Plugins: provides an installable list of associated plugins. For an example, search for “firefox” and open its “Plugins” tab.
  • Similar: provides an installable list of applications that provide similar functionality.
  • Build Options: shows the values of the make options that the PBI or package was built with.

Once you find a PBI that you would like to install, click on its “Install Now!” icon. A yellow status bar at the bottom of the screen will show the download and installation status. Once the installation is complete, some of the contents of this screen will change, as seen in the example in Figure 7.1c.

Figure 7.1c: Viewing the Information for an Installed Application

The “Install Now!” button will change to “Installed” and the following buttons are now available:

  • Launch: provides a drop-down menu for starting the application from its available start modes. Some applications start in graphical mode, some in command-line mode, and some offer both modes.
  • Contact Maintainer: if this button is clicked, a pop-up message offers to launch the default email client, if one has been configured. It also indicates the email address of the FreeBSD port maintainer for that application in case one prefers to manually open their email client. If a default email client is configured, it will automatically fill in this email address so that you can send feedback to the maintainer. Typically, this is done to send an error report or a patch to the maintainer.
  • Shortcuts: click this button to add or remove a desktop shortcut to the application.

Managing Installed Software

To manage software that is currently installed, use the “Installed” tab. Figure 7.1d shows a screenshot of this tab after “gimp” is successfully installed.

Figure 7.1d: Viewing the List of Installed Software in AppCafe®
Figure 7.1e: Upgrading Installed PBIs

The list of installed applications can be sorted by “Program name”, “Version”, “Status” (of any running/pending “Actions”), “Size”, “Installed” (date of installation), and “Architecture”. Click the name of the desired column to change the sorting.

If you check the box for at least one installed application and click the “Actions” button, the following actions become available:

  • Desktop Icons: used to add or remove a shortcut to the application on any installed desktop that supports icons.
  • Version Lock: used to “Lock Current Version” so that it will not be updated until “Unlock Application” is selected. An application that is locked will have a lock icon next to its “Version”. Locking an application can be appropriate if there is a known issue in a more recent version of the application.
  • Uninstall: will uninstall the checked applications. Once the removal is complete, that software will be removed from the “Installed” list.
  • Cancel Actions: cancels any currently pending or running operations such as uninstallation, updating, or installation.

If you click the “Application Details” button, it will display the details for the application, as seen in the example shown in Figure 7.1c.

Updating Installed Software

As seen in the previous screenshots, AppCafe® will indicate if “Application updates are available!”. This message will automatically appear when any installed software has a newer version available. To start an update, click the “Start Updates” button. This will open the screen shown in Figure 7.1e.

In this example, the “Show Details” button was clicked in order to view the list of outdated software. The listing will show the current version as well as the newer version for the software as well as any affected dependencies and will end with the size for the amount of new software to be downloaded.Click “Yes” to start the upgrade or “No” to cancel the upgrade request.

Once the upgrade is started, a status bar will indicate the progress of the download and upgrade process in an “Overview” tab. To see more detailed messages, click the “Update Details” tab. The upgrade process will save all of the current version's settings. For example, when Firefox is upgraded, it will keep all of your bookmarks, history, and cache.

Figure 7.1f Watching the Upgrade Progress

This screen will indicate when the upgrade is finished and will offer to reboot the system if the upgrade requires a reboot. If a reboot is needed and you cancel it, finish saving your work then reboot the system manually.

File Menu

The “File” menu provides the following options:

  • Vulnerability Info: if you click this menu option, the FreshPorts VuXML page will open in the default web browser. This contains a list of all known vulnerabilities to software which has been ported to FreeBSD, and is thus available for installation in PC-BSD®. By default, the most recent vulnerabilities are shown first. There is a link on that web page to order the list of vulnerabilities by package name.
  • Import PBI List: if you click this option, it will ask you to browse to the location of an existing PBI list, an ASCII text file ending with a .pbilist extension that contains the names of PBIs (without a version number), one per line. An example is seen in Example 7.1a. If you import a PBI list into AppCafe®, it will add those applications to the installation queue so that they can be installed. AppCafe® will ignore any invalid lines and PBIs which are already installed.

  • Export PBI List: if you click this option on a system that already has PBIs installed, you can then import that list into another PC-BSD® system. By default, the exported list will be saved as exportfile.pbilist.
  • Quit: click this option to close AppCafe®.

Example 7.1a: Sample PBI List


thunderbird firefox qtcreator scite gimp pithos quassel ksnapshot


Configure Menu

The "Configure" menu contains the following options:

  • Repository Settings: as seen in Figure 7.1g, this option is used to select the package set. "Production" is the default and recommended setting for most users. Software updates are provided every three months, which gives sufficient time for new software versions to be tested. "Edge" is meant for users who wish to assist with software testing or who can tolerate the occasional breakage caused by installing new software versions. Software updates are provided approximately every two weeks. "Custom" is for administrators who have created their own PBI repository; click the “+” button to browse to the location of the custom .rpo file. To allow switching between custom repositories, multiple custom repositories can be listed, but only the one marked as active will be used.
  • Refresh PBI Index: click this option to get the latest copy of the list of available PBIs and packages. Otherwise, this list is automatically refreshed each time AppCafe® is started.
  • Developer Mode: check this box to add a pane of debugging messages to the bottom of AppCafe®. This can be useful to help determine the problem if there is an error in installing or upgrading software.
Figure 7.1g: AppCafe® Repository Settings Menu

Install View Menu

The default AppCafe® view only provides information about PBIs but does not provide information about packages. This means that the “Installed” tab will only show installed PBIs and the “Browse for Apps” tab and search function will only display available PBIs. This default can be changed using the options in the “Install View” menu, which changes the appearance of the "Install" tab, and “Browser View” menu, which changes the appearance of the "Browse for Apps" tab.

The “Install View” menu contains the following options:

  • Show Raw Packages: when this box is checked, it adds the list of installed packages to the list of installed PBIs. An example is seen in Figure 7.1h.
  • Show Orphan Packages: when this box is checked, the contents of the “Installed” tab change to the list of installed software which are not dependencies of any other installed application. An example is shown in Figure 7.1i. The list will either be PBIs or PBIs and packages, depending upon whether or not “Show Raw Packages” is also checked.
  • Show Base Packages: when this box is checked, the contents of the “Installed” tab change to the list of installed base system packages, or the packages which get installed with the operating system. If “Show Raw Packages” is also checked, the listing will include every installed package rather than just the name of the system component. An example is seen in Figure 7.1j.
Figure 7.1h: List of Raw Packages
Figure 7.1i: List of Orphan Packages
Figure 7.1j: List of Base Packages

By default, AppCafe® displays software information for the computer running PC-BSD®. It can also be used to manage the software running in a jail, as long as at least one jail has been created and is running. To manage a jail, click the “Jail” button and select the name of the jail in the drop-down menu. If this button and menu are greyed out, it means that no jails are running. Start the desired jail in Warden® and click the “Jail Check” button to tell AppCafe® to look for the running jail.

Browser View Menu

The “Browser View” menu determines which software appears in the “Browse for Apps” tab and the results of a software search. By default, the following options are checked: “Graphical Apps” (white window with blue stripe icon), “Text Apps” (black terminal icon), and “Server Apps” (blue globe icon).

To also view packages, check the box for “Raw Packages” (brown box icon). It may take a minute or two for the list of available packages to populate.

Any combination of checked boxes is supported, making it easier to zero in on the types of applications one is interested in finding.

Using the CLI pkg Utilities

For managing packages from the command line, PC-BSD® uses pkgng, the next generation package management system for FreeBSD. To manage PBIs from the command line, refer to PBI Manager.

If you are used to using the traditional FreeBSD package system, take note that the commands used to install and manage software differ slightly. For example, instead of using pkg_add to install a package from a remote repository, use pkg install or pc-pkg install (notice there is now a space instead of an underscore).

The FreeBSD Handbook[2] provides an introduction to using pkgng. Section 5.4.1 is not needed on a PC-BSD® or TrueOS® system as the operating system installation does this for you. The various pkgng commands have associated man pages. Type man pkg for an overview of general usage; the names of the associated man pages will be found towards the bottom of this man page. Once you know the name of a command, you can also use the built-in help system to get more information about that command. For example, to learn more about pkg install, type pkg help install.

Upgrading Packages

In addition to the pkg upgrade command provided by pkgng, PC-BSD® provides the pc-updatemanager command for upgrading packages.

To determine if newer versions of packages are available using this command, type the following as the superuser:

pc-updatemanager pkgcheck                                                       

  Updating repository catalogue   Upgrades have been requested for the following 253 packages:   list of packages snipped   The upgrade will require 70 MB more space   439 MB to be downloaded

  To start the upgrade run "/usr/local/bin/pc-updatemanager pkgupdate"

In this example, newer versions are available for 253 packages. The list of package names was snipped from the sample output. If no updates were available, the output would have instead said "All packages are up to date!".

If updates are available, you can install them with this command:

pc-updatemanager pkgupdate                                                      

  Updating repository catalogue   snip downloading and reinstalling output   [253/253] Upgrading pcbsd-base from 1374071964 to 1378408836... done

  Extracting desktop overlay data...DONE

While the output has been snipped from this example, the update process will download the latest versions of the packages which need updating, displaying the download progress for each file. Once the downloads are complete, it will display the reinstallation process for each file. The last step of the update process is to extract the desktop (or server) overlay and then to return the prompt.

How long the package upgrade takes depends upon the number of packages and the speed of the Internet connection. If you run this command on a desktop, you should log out and log in again so that you load the latest version of the desktop and its applications. If you run this command on a server while running the tcsh shell, type rehash in order to tell the shell that new applications have been installed.


  1. wiki.pcbsd.orgtxt=PC-BSD® wiki
Other languages:German 18% • ‎English 100%
Personal tools