Jails
NOTE: in FreeNAS® 8.2.x and 8.3.x, this part of the GUI was found in Services -> Plugins.
In FreeNAS® 9.0.1, the FreeNAS® plugin system was redesigned to allow for multiple jails.
The FreeNAS® plugin system uses a FreeBSD jail to provide an environment for the installation of additional software. In FreeNAS®, this jail is referred to as the Plugins Jail. The jail itself and the installation of software within the jail are managed from Services → Plugins.
A FreeBSD jail provides light-weight, operating system-level virtualization which essentially allows the creation of an independent FreeBSD operating system running on the same hardware. This means that any software and configurations within a jail are isolated from the FreeNAS® operating system. The FreeNAS® implementation includes the vimage jail add-on which provides the Plugins Jail with its own, independent networking stack. This allows the Plugins Jail to do its own IP broadcasting, which is required by some PBIs.
Once the Plugins Jail is installed, the FreeNAS® plugin architecture supports the installation and configuration of PBIs using the FreeNAS® GUI. PBIs were created by the PC-BSD project to provide a graphical installation wrapper to software which has been ported to FreeBSD. FreeNAS® PBIs extend this functionality by providing a graphical front-end to the application's configuration file and by allowing the service to be started and stopped within the FreeNAS® GUI.
Since the Plugins Jail is essentially a FreeBSD installation running within FreeNAS®, you can also install software using FreeBSD ports and packages. This is convenient when a PBI is not yet available for the software that you need. However, installing manually within the jail means that you also have to configure the software manually within the jail (i.e. its configuration options will not show up in the FreeNAS® GUI).
This section demonstrates how to install the Plugins Jail, how to find, install, and configure PBIs, and then provides an overview of the PBIs which are available with FreeNAS® 8.3.0-RELEASE. It then explains the plugin architecture, how to create your own PBIs, and how to install non-PBI software using the FreeBSD ports and packages collections.
Contents |
Installing the Plugins Jail
The Plugins Jail can be installed to a UFS or ZFS filesystem. While it can be installed into a directory, it is recommended to instead create two ZFS datasets: one to hold the FreeBSD operating system and one to hold the software that you install. This section describes a sample configuration that uses two ZFS datasets.
NOTE: if you plan on using Mount Points be aware that path size within the Plugins Jail is limited to 88 characters. Make sure that the length of your volume name plus the dataset name plus the jail name will not exceed this limit.
1. Create two ZFS datasets: one for the jail itself and one to hold the installed software. In this example, a volume named /mnt/volume1 has a dataset named jail, which will hold the jail itself, and a second dataset named software, which will hold the installed software.
NOTE: do not create a dataset less than 2GB in size. If you set a quota on the dataset, make sure that the size will be sufficient to hold the FreeBSD operating system (2GB), the software you intend to install, and any logs and data used by the applications that you install.
2. Download the plugins_jail PBI located in the plugins folder for your architecture from the 8.3.1 SourceForge page.
3. Create the jail using Services → Plugins → Management → Settings. The initial pop-up message will ask where you would like to temporarily place the jail PBI file. Use the drop-down menu to select a volume (in this example, /mnt/volume1), then press OK to see the screen shown in Figure 8.10a.
Figure 8.10a: Install the PBI Jail
In this example, the Plugins Jail path is /mnt/volume1/jail, the Jail name is software, the Jail IP address is reachable by the FreeNAS® system, the Jail IP Netmask associated with the Jail IP address has been selected, and the Plugins Path is /mnt/volume1/software. Table 8.10a summarizes these options.
NOTE: the Plugins Jail will not work and installed PBIs will not show up in the GUI if the Jail IP Address is not pingable from the FreeNAS® system. An incorrect Jail IP Netmask can make the IP address unreachable. On systems with multiple interfaces there is currently no way to specify which interface is used as the Plugins Jail chooses the interface with the default gateway. If a default gateway is not set on the FreeNAS® system, add it in Network → Global Configuration. At this time, IPv6 is not supported within the Plugins Jail. If you are using VMware, make sure that the vswitch is set to promiscuous mode.
Table 8.10a: Jail Configuration Options
| Setting | Value | Description |
| Plugins jail path | browse button | mandatory; browse to the directory or ZFS dataset where the jail will be installed |
| Jail name | string | mandatory; can only contain letters and numbers |
| Jail IP address | string | mandatory; input an IP address that is reachable by the FreeNAS® system and which is unique on the network |
| Jail IP Netmask | drop-down menu | mandatory; select the subnet mask associated with the Jail IP address |
| MAC | string | ptional; set a permanent MAC address when using port forwarding or MAC address security on a router to bypass the default of changing the MAC address when the system reboots |
| Plugins archive path | browse button | mandatory; browse to the directory or ZFS dataset where the software will be installed |
Once you complete the fields and click the Upload Jail PBI button, you will be prompted to browse to the Plugins Jail PBI that you downloaded. Press the Upload Jail PBI button again and the Plugins Jail will be installed.
4. Start the plugins service. The Plugins Jail and any installed software will not be available whenever this service is not enabled. In Services → Control Services, click the red OFF button next to Plugins in the Core tab. After a second or so, it will change to a blue ON, indicating that the jail has been enabled and is now available for use.
5. Decide how you wish to install software. If a plugin is available for the software that you need, use the instructions in Installing Software Using an Existing Plugin PBI.
If a plugin is not available and you wish to create your own PBI, use the instructions in Creating your own FreeNAS® PBIs.
If a plugin is not available or you prefer to manually install from the command line, use the instructions in Installing non-PBI Software.
Managing the Plugins Jail
Once the Plugins Jail is installed and started, you can manage mount points, change the jail's settings, delete the jail, import the jail, or update the jail.
Mount Points
Services → Plugins → Management → Mount Points allows you to add and manage mount points which can be used by PBIs that store a large amount of data. An example would be transmission, which stores torrents. Mount points use mount_nullfs(8) to "link" data that resides outside of the jail as a mount point within the jail.
To add a mount point, click Services → Plugins → Management → Mount Points → Add Mount Point. You will be prompted to browse to the Source and Destination, where:
- Source: is the directory on the FreeNAS® system. This directory resides outside of the jail and will provide storage (e.g. for transmission's torrents).
- Destination: is the mount point within the jail. An example would be /mnt/volume1/jail/plugins/mnt.
The GUI will not let you create a mount point where the Source is recursive. For example, if the jail is installed into /mnt/volume1/jail, using a Source beginning with /mnt/volume1/jail would fail, whereas a Source of /mnt/volume1/someotherdir/somedir will work.
NOTE: a mount point provides a pointer to the data on the FreeNAS® system, it is not a copy of that data. This means that if you delete any files from the Destination directory located in the jail, you are really deleting those files from the Source directory located on the FreeNAS® system.
Jail Settings
If you click Services → Plugins → Settings, you will see a screen similar to Figure 8.10b.
Figure 8.10b: Plugins Jail Settings
This screen allows you to view the settings for the Plugins Jail and to modify the jail's IP address, subnet mask, and MAC address. This screen also provides the following buttons:
Delete: if you delete the Plugins Jail, it will also delete all of the PBIs that you installed. Should you choose to delete the Plugins Jail, your browser color will change to red to indicate that you have selected an option that could negatively impact users of the FreeNAS® system. The pop-up message shown in Figure 8.10c will also be displayed.
Figure 8.10c: Deleting the Plugins Jail
Since deleting the jail also deletes any installed software, you must first check the box indicating that you are sure that you want to delete the jail before FreeNAS® will perform this operation.
Import Plugins Jail: if you import or auto-import a disk that already contains a Plugins Jail (e.g. after a fresh install or lost configuration), you do not need to reinstall the Plugins Jail. Instead you can import the jail, which will add it back to the Services → Plugins tree of the GUI.
NOTE: at this time, it is not possible to export a jail or save the jail's configurations from the GUI.
The Import Plugins Jail button, shown in Figure 8.10d, will prompt for the Plugins Jail path, the IP address and subnet mask of the jail, and the plugins archive path. Once the import is complete, start the Plugins service in Services → Control Services.
Figure 8.10d: Importing a Plugins Jail
Update Plugins Jail: should a newer version of the Plugins Jail become available, use the Update Plugins Jail button to upgrade to the latest version. Before beginning the upgrade, you must first stop the Plugins service or the upgrade will fail. This means that you should upgrade at a time that will least impact users of the services installed within the Plugins Jail. To start the upgrade, click the Update Plugins Jail button; the resulting pop-up window will prompt for the dataset to temporarily place the PBI file. Click the OK button and you will be prompted to browse to the location of the new Plugins Jail PBI. Click the Upload Jail PBI button to perform the upgrade. When the upgrade is complete, don't forget to restart the Plugins service in Services → Control Services.
Accessing the Plugins Jail
If you need to administer the contents of the Plugins Jail, make sure that the Plugins service is showing as ON in Services → Control Services, then open Shell. To determine the ID being used by the jail, use the jls command:
jls JID IP Address Hostname Path 1 - software /mnt/volume1/jail/software
In this example, the jail ID is 1 and the IP Address is listed as "-", which is to be expected. To access the jail, provide the jail ID and the shell that you would like to use as options to the jexec command:
jexec 1 /bin/tcsh software#
The software# prompt (hostname of the jail) indicates that you are now inside the Plugins Jail.
By default, ssh access is not configured for the Plugins Jail and it can only be accessed through Shell.
To configure ssh access, perform the following within the Plugins Jail.
First, add the following line to /etc/rc.conf:
sshd_enable="YES"
After saving the file, start the ssh daemon:
service sshd start
The host RSA key pair should be generated and the key's fingerprint and random art image displayed.
Next, add a user account which will be used to ssh into the jail. Since the user will want to have superuser privileges, the user needs to be placed in the wheel group. To create the user, type adduser and follow the prompts. When you get to this prompt, do not press enter but instead type wheel:
Login group is user1. Invite user1 into other groups? []: wheel
Once the user is created, test from another system that the user can successfully ssh in and become the superuser. In this example, a user named user1 is ssh'ing into the Plugins Jail at 192.168.2.3. The first time the user logs in, they will be asked to verify the fingerprint of the host:
ssh user1@192.168.2.3 The authenticity of host '192.168.2.3 (192.168.2.3)' can't be established. RSA key fingerprint is 6f:93:e5:36:4f:54:ed:4b:9c:c8:c2:71:89:c1:58:f0. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '192.168.2.3' (RSA) to the list of known hosts. Password: 'type_password_here $ su jail#
Installing Software Using an Existing Plugin PBI
Official PBIs are available for download from the plugins folder for your architecture at the 8.3.1 Sourceforge page. PBIs end in a .pbi extension. Each plugin has an associated sha256 checksum, which can be found in its .pbi.sha256.txt file.
NOTE: additional PBIs are available from this page of the forums. These PBIs are still being tested; if you experience any problems using one of these PBIs, leave your feedback for the plugin author so that the PBI can be improved.
To install a PBI, go to Services → Control Services → Plugins tab → Install Plugin. Use the Browse button to locate the downloaded PBI and click the Upload button to install the PBI. In the example shown in Figure 8.10e, the user has browsed to the location of the downloaded transmission PBI.
Figure 8.10e: Installing a PBI
Once installed, an entry for the plugin will be added to the Services → Control Services → Plugins tab, as seen in the example shown in Figure 8.10g. Each entry indicates the name of the plugin, the software version, the name of the PBI (which includes the architecture), the status of the service, and buttons to Update or Delete the PBI.
An entry for each plugin will also be added to the tree in Services → Plugins, as seen in Figure 8.10f. Click that entry to open that plugin's configuration options. These options are discussed in more detail in the next section.
NOTE: if an entry is not added to the Services → Plugins tree, there is a problem with the IP address and/or subnet mask configured for the Plugins Jail. Check that these values are correct and reachable by the FreeNAS® system in Services → Plugins → Settings.
Figure 8.10f: Viewing Installed PBIs
To start the application associated with the entry, click its red OFF button. If the service successfully starts, it will change to a blue ON.
NOTE: always review a PBI's configuration options before attempting to start it in Services → Control Services. Some PBIs have options that need to be set before their service will successfully start. The available options will vary by PBI; the configuration options for the Firefly, MiniDLNA, and Transmission PBIs are described in the next section.
Popular PBIs
This section will summarize the configuration options for the PBIs that are available with FreeNAS® 8.3.0-RELEASE. Over time, as more PBIs become available, the most popular PBIs will be added to this section.
This section is meant to be a guide to get you started with configuring installed software. It is not meant to provide an exhaustive how-to for each software that is available as a PBI. Whenever you configure any software for the first time, refer to the documentation provided by the software, and when none exists, expect to spend some time researching the software's capabilities.
Firefly
Firefly Media Server is an open source media server used to serve media files for Roku and iTunes. It was formerly called mt-daapd which is why the binary is mt-daapd and the configuration file is named mt-daapd.conf. Once configured and started, the firefly service provides its own web administrative interface for configuring playlists and forcing index scans.
NOTE: the firefly project is no longer maintained. Another fork, forked-daapd, has not been ported to FreeBSD yet. The port request is here.
Once the firefly PBI is installed, its options can be configured in Services → Plugins → Firefly. Figure 8.10g shows the configuration screen for firefly and Table 8.10b summarizes the configuration options.
Figure 8.10g: Firefly Configuration Screen
Table 8.10b: Firefly Configuration Options
| Setting | Value | Description |
| Port | integer | defaults to 3689, the default iTunes port |
| Admin pw | string | mandatory; the password to access the web administration interface |
| Servername | string | the name of the server as advertised via rendezvous and the name of the database exported via DAAP; default displays the version number (%v) and the system's hostname (%h) |
| Extensions | string | comma separated list (no spaces) of the file extensions that will be indexed and served |
| MP3 directory | browse button | mandatory; browse to the location that will store the shared mp3 files |
| Log file | browse button | browse to the location within the Plugins Jail to store the firefly log file |
| Rescan interval | integer | how often to check to see if any mp3 files have been added or removed; empty or 0 disables background scanning, though a a scan can still be forced from the "status" page of the administrative web interface; automated scanning may waste CPU and increase connection times to the server |
| Always scan | checkbox | if left unchecked, background rescans of the filesystem at each "Rescan interval" are disabled unless clients are connected, in order to allow the drives to spin down when not in use; checking this box will scan every Rescan interval |
| Scan type | drop-down menu | sets how aggressively mp3 files should be scanned to determine file length; Normal scans the first mp3 frame to try and calculate size and should be accurate for most files except for VBR files without a Xing tag; Aggressive checks the bitrates of 10 frames in the middle of the song and will still be inaccurate for VBR files without a Xing tag; Painfully aggressive walks through the entire song, counting the number of frames, which will be accurate, takes the most time, but will only occur the first time the file is indexed |
| Process playlists | checkbox | whether or not to process playlists |
| Process iTunes | checkbox | whether or not to process iTunes |
| Process m3u | checkbox | whether or not to process m3u |
| Auxiliary parameters | string | additional parameters not covered by other option fields; these are described in the file /usr/local/etc/mt-daapd.conf.sample which is installed with the Firefly PBI within the Plugins Jail |
Once you have saved your configuration values, start the firefly service using Services → Control Services → Plugins tab.
If you wish to access firefly's built-in administrative GUI, use a web browser to input the IP address of your Plugins Jail followed by a colon and the Port number you configured (the default is 3689). It will prompt for a username and password: input admin as the username and use the value you configured for Admin pw as the password. The firefly administrative interface is shown in Figure 8.10h. In this example, the PBI jail address is 10.0.0.1, the port is 3689, and the smart playlists configuration screen is open.
Figure 8.10h: Firefly Web Administrative Interface
MiniDLNA
MiniDLNA is an open source DLNA server that uses UPnP for media management, discovery and control. The MiniDNLA daemon serves media files such as music, pictures, and video to clients on a network. Example clients include applications such as totem and xbmc, and devices such as portable media players, smartphones, and televisions. Unlike firefly, it does not provide its own web interface for administration.
Once the MiniDLNA PBI is installed, its options can be configured in Services → Plugins → MiniDLNA. Figure 8.10i shows the configuration screen for MiniDLNA and Table 8.10c summarizes the configuration options.
Figure 8.10i: MiniDLNA Configuration Screen
Table 8.10c: MiniDLNA Configuration Options
| Setting | Value | Description |
| Friendly name | string | optional; set this if you want to customize the name that shows up on your clients |
| Media directory | browse button | mandatory; browse to or enter the location of the directory to store the media files; see NOTE below |
| Port | integer | HTTP port for descriptions, SOAP, and media transfer traffic; default is 8200 |
| Discover interval | integer | how often MiniDLNA broadcasts its availability on the network; default is every 895 seconds |
| Strict DLNA | checkbox | if checked will strictly adhere to DLNA standards which will allow server-side downscaling of very large JPEG images and may hurt JPEG serving performance on Sony DLNA products |
| Model number | integer | model number the daemon will report to clients in its XML description; default is 1 |
| Serial | integer | serial number the daemon will report to clients in its XML description; default is 12345678 |
| Rescan on (re)start | checkbox | whether or not the media files are scanned when the MiniDLNA is started or restarted |
| Auxiliary Parameters | string | additional parameters available in minidlna.conf(5) and not covered by other option fields |
NOTE: the Media Directory must be accessible inside the jail so in most cases you will want to add a Mount Point that mounts a directory from the FreeNAS® filesystem to a directory inside the Plugins Jail. For example, create a Mount Point with a source of /mnt/volume1/Video and a destination of /mnt/volume1/jail/software/media. To restrict the media type, add a qualifier to the Auxiliary Parameters section. Examples of qualifiers can be found in the "media_dir" section of minidlna.conf(5).
Once you have saved your configuration values, start the MiniDLNA service using Services → Control Services → Plugins tab.
Transmission
Transmission is an open source BitTorrent client. Its features include encryption, a web interface, peer exchange, magnet links, DHT, µTP, UPnP and NAT-PMP port forwarding, webseed support, watch directories, tracker editing, and global and per-torrent speed limits.
Once the Transmission PBI is installed, its options can be configured in Services → Plugins → Transmission. Figure 8.10j shows the configuration screen for Transmission and Table 8.10d summarizes the available configuration options. More information about these options can be found at the Editing Configuration Files page of the Transmission wiki.
Figure 8.10j: Transmission Edit Screen
Table 8.10d: Transmission Configuration Options
| Setting | Value | Description |
| Watch Directory | browse button | browse to the directory transmission will watch for new torrent files |
| Configuration Directory | browse button | browse to the directory where transmission will store its configuration files |
| Download Directory | browse button | browse to the directory where files will be downloaded to |
| Allowed | string | comma-delimited list of allowed IP addresses; supports wildcards (e.g. 127.0.0.1,192.168.*.*) |
| Blocklist | string | comma-delimited list of blocklists stored in the blocklists subdirectory of Configuration Directory; if you add a new blocklist, restart the transmission service |
| Logfile | browse button | browse to the directory within the Plugins Jail to store the transmission log file |
| RPC/WebUI Enabled | checkbox | uncheck this box to disable the transmission web administrative interface |
| RPC Port | integer | port to listen for RPC requests on; default is 9091 |
| RPC Auth Required | checkbox | if enabled, clients are required to authenticate; requires Username and Password fields to be configured |
| RPC Username | string | mandatory if RPC auth required checked; username to use for authentication |
| RPC Password | string | mandatory if RPC auth required checked; password to use for authentication |
| RPC Whitelist Enabled | checkbox | if checked, only the addresses listed in RPC Whitelist will be granted remote access |
| RPC Whitelist | string | comma-delimited list of IP addresses from which remote control is permitted |
| Distributed Hash Table (DHT) | checkbox | when enabled, the DHT protocol is used to track peers downloading torrents without the use of a standard tracker; the protocol stores lists of other nodes/peers which can be used to locate new peers |
| Local Peer Discovery (LPD) | checkbox | enables the discovery of BitTorrent peers located on the same LAN |
| Micro Transport Protocol (uTP) | checkbox | enables BitTorrent over UDP |
| Peer port | integer | port to listen on for incoming peer connections; default is 51413 |
| Portmap | checkbox | enable this to allow other peers to connect to you; instructions for allowing transmission through firewalls/routers are here |
| Max number of peers | integer | maximum number of connected peers; default is 240 |
| Max number of peers per torrent | integer | maximum number of connected peers for an individual torrent; default is 60 |
| Encryption | drop-down menu | choices are: prefer unencrypted (encryption will not be used unless the client requires it), prefer encrypted (encryption will be used if the client supports it), require encrypted (clients must support encryption) |
| Global Seed Ratio | integer | how much you have downloaded v.s. how much you have uploaded; all torrents, unless overridden by a per-torrent setting, should seed until specified ratio; default is 2 |
Once you have saved your configuration values, start the transmission service using the Services → Control Services → Plugins tab.
If you wish to access transmission's built-in administrative GUI, use a web browser to input the IP address of your Plugins Jail followed by a colon and the RPC port number you configured (the default is 9091). It will prompt for a username and password and by default you can just press enter to access the interface. If you checked the RPC auth required box, input the RPC username and RPC password that you specified in your configuration.
The transmission website has a screenshot of the administrative interface here. A Transmission Support Forum is also available.
Installing non-PBI Software
If a PBI is not available for the software that you wish to install, you can still install and configure the application from the command line using either the FreeBSD ports or packages collection. This section will describe both methods of software installation. You should skim through the entire section first to determine which method of software installation best meets your needs.
Before you can install software a FreeBSD package or port, you will need to access the Plugins Jail. The commands demonstrated in this section need to be executed from within the Plugins Jail .
Installing FreeBSD Packages with pkg_add
The quickest and easiest way to install software inside the jail is to install a FreeBSD package. A FreeBSD package is pre-compiled, meaning that it contains all the binaries and dependencies required for the software to run on a FreeBSD system.
A lot of software has been ported to FreeBSD (currently over 24,000 applications) and most of that software is available as a package. The best way to find FreeBSD software is to use FreshPorts.org.
Figure 8.10k shows the search results for openvpn.
Figure 8.10k: FreshPorts Search Results
The search indicates that seven ports are currently available. Each port includes the name of the software, the version, a description, the category (e.g. security), the email address of the port's maintainer, a CVSWeb link containing the details of the port, and a link to the software's main website. Each entry includes the command used to compile the port (as described in the next section) and the pkg_add -r command used to install the package.
For example, to install openvpn 2.2.2, use the command that FreshPorts indicates to add the package:
pkg_add -r openvpn Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/amd64/packages-8.3-release/Latest/openvpn.tbz... Done. Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/amd64/packages-8.3-release/All/lzo2-2.04.tbz... Done. ### ------------------------------------------------------------------------ ### Edit /etc/rc.conf[.local] to start OpenVPN automatically at system ### startup. See /usr/local/etc/rc.d/openvpn for details. ### ------------------------------------------------------------------------ ### For compatibility notes when interoperating with older OpenVPN ### versions, please, see <http://openvpn.net/relnotes.html> ### ------------------------------------------------------------------------ software#
The installation messages indicate that the package and its dependency (lzo2) successfully downloaded. This port provides a post-installation message indicating how to start the service at boot time.
You can confirm that the installation was successful by querying the package database:
pkg_info -ox openvpn Information for openvpn-2.2.2: Origin: security/openvpn
To see what was installed with the package:
pkg_info -Lx openvpn | more Information for openvpn-2.2.2: Files: /usr/local/man/man8/openvpn.8.gz /usr/local/sbin/openvpn /usr/local/lib/openvpn-auth-pam.so /usr/local/lib/openvpn-down-root.so /usr/local/share/doc/openvpn/AUTHORS /usr/local/share/doc/openvpn/COPYING /usr/local/share/doc/openvpn/COPYRIGHT.GPL /usr/local/share/doc/openvpn/ChangeLog /usr/local/share/doc/openvpn/INSTALL /usr/local/share/doc/openvpn/PORTS /usr/local/share/doc/openvpn/README /usr/local/share/doc/openvpn/README.openvpn-auth-pam <snip output>
In FreeBSD, third-party software is always stored in /usr/local to differentiate it from the software that came with the operating system. Binaries are almost always located in a subdirectory called bin or sbin and configuration files in a subdirectory called etc.
You can also research ahead of time which files will be installed with a package by clicking the CVSWeb link for the software at FreshPorts. Click the version number for the pkg-plist file. Here is a portion of the pkg-plist for openvpn:
sbin/openvpn lib/openvpn-auth-pam.so lib/openvpn-down-root.so %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/COPYING
Note that pkg-plist always assumes /usr/local. For example, when reading sbin/openvpn, think /usr/local/sbin/openvpn. %%PORTDOCS%%%%DOCSDIR%% is a substitution for /usr/local/share/doc/name_of_package, as you can see from the pkg_info -Lx output.
Compiling FreeBSD Ports with make
Typically, software is installed using the pkg_add command. Occasionally you may prefer to compile the port yourself. Compiling the port offers the following advantages:
- not every port has an available package. This is usually due to licensing restrictions or known, unaddressed security vulnerabilities.
- sometimes the package is out-of-date and you need a feature that became available in the newer version.
- some ports provide compile options that are not available in the pre-compiled package. These options are used to add additional features or to strip out the features you do not need.
Compiling the port yourself has the following dis-advantages:
- it takes time. Depending upon the size of the application, the amount of dependencies, the amount of CPU and RAM on the system, and the current load on the FreeNAS® system, the amount of time can range from a few minutes to a few hours or even to a few days.
NOTE: if the port doesn't provide any compile options, you are better off saving your time and the FreeNAS® system's resources by using the pkg_add command instead.
You can determine if the port has any configurable compile options by clicking on its CVSWeb link in FreshPorts. To continue the example shown in Figure 8.10k, Figure 8.10l shows the results when the CVSWeb link is clicked for openvpn 2.2.2.
Figure 8.10l: Reading a Port's CVSWeb in FreshPorts
In FreeBSD, a Makefile is used to provide the compiling instructions to the make command. CVSWeb keeps a history of every version of the port. For example, if you click the hyperlink for "Makefile" you will see a history of all of that port's Makefiles, as well as their commit descriptions. To read the contents of the current Makefile, instead click on the version number (in this example, 1.59). The Makefile is in ascii text, fairly easy to understand, and documented in bsd.port.mk.
If the port has any configurable compile options, they will be listed under OPTIONS. This Makefile contains the following OPTIONS:
OPTIONS= PW_SAVE "Interactive passwords may be read from a file" off \
PKCS11 "Use security/pkcs11-helper" off
FreeBSD packages always use the default OPTIONS. In this example, the two options are disabled, meaning that those features won't be available unless you compile the port yourself. When you compile the port, those options will be presented to you in a menu, allowing you to change their default settings.
Before you can compile a port, you must install the ports collection. This can be done using the portsnap utility.
portsnap fetch extract
This command will download the ports collection and extract it to the /usr/ports/ directory.
NOTE: if you install additional software at a later date, you should make sure that the ports collection is up-to-date using this command:
portsnap fetch update Ports tree is already up to date.
To compile a port, you will cd into a subdirectory of /usr/ports/.
The following example will compile the openvpn 2.2.2 port shown in Figures 8.10k and 8.10l. FreshPorts provides the location to cd into and the make command to run:
cd /usr/ports/security/openvpn make install clean
Since this port's Makefile includes OPTIONS, we will see the configure screen shown in Figure 8.10m when the make command is issued:
Figure 8.10m: Configuration Options from the Port's Makefile
To change an option's setting, use the arrow keys to highlight the option, then press the spacebar to toggle the selection. Once you are finished, tab over to OK and press enter. The port will begin to compile and install.
NOTE: if you change your mind, the configuration screen will not be displayed again should you stop and restart the build. Type make config && make install clean if you need to change your selected options.
If the port has any dependencies with options, their configuration screens will be displayed and the compile will pause until it receives your input. It is a good idea to keep an eye on the compile until it finishes and you are returned to the command prompt. If you need to perform other configuration tasks, click the x in the upper right corner of Shell. This will detach from the jail without pausing the compile process--when you click Shell again you will be returned to the jail and can view the current progress of the compile.
Once the port is installed, it is registered in the same package database that manages packages. This means that you can use pkg_info to determine what was installed, as described in the previous section.
Configuring and Starting the Software
Once the package or port is installed, you will need to configure and start it. If you are familiar with how to configure the software, look for its configuration file in /usr/local/etc or a subdirectory thereof. Many FreeBSD packages contain a sample configuration file to get you started. If you are unfamiliar with the software, you will need to spend some time at the software's website to learn which configuration options are available and which configuration file(s) need to be edited.
Most FreeBSD packages that contain a startable service include a startup script which is automatically installed to /usr/local/etc/rc.d/. Once your configuration is complete, you can test that the service starts by running the script with the onestart option. These commands will run the openvpn startup script and verify that the service started:
/usr/local/etc/rc.d/openvpn onestart Starting openvpn. /usr/local/etc/rc.d/openvpn onestatus openvpn is running as pid 45560. sockstat -4 USER COMMAND PID FD PROTO LOCAL ADDRESS FOREIGN ADDRESS root openvpn 48386 4 udp4 *:54789 *:*
If you instead receive an error:
/usr/local/etc/rc.d/openvpn onestart Starting openvpn. /usr/local/etc/rc.d/openvpn: WARNING: failed to start openvpn
Run tail /var/log/messages to see if any error messages hint at the problem. Most startup failures are related to a mis-configuration: either a typo or a missing option in a configuration file.
Once you have verified that the service starts and is working as intended, add a line to /etc/rc.conf to ensure that the service automatically starts whenever the Plugins Jail service starts. The line to start a service always ends in _enable="YES" and typically starts with the name of the software. For example, this is the entry for the openvpn service:
openvpn_enable="YES"
When in doubt, the startup script will tell you which line to put in /etc/rc.conf. This is the description in /usr/local/etc/rc.d/openvpn:
# This script supports running multiple instances of openvpn. # To run additional instances link this script to something like # % ln -s openvpn openvpn_foo # and define additional openvpn_foo_* variables in one of # /etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d /openvpn_foo # # Below NAME should be substituted with the name of this script. By default # it is openvpn, so read as openvpn_enable. If you linked the script to # openvpn_foo, then read as openvpn_foo_enable etc. # # The following variables are supported (defaults are shown). # You can place them in any of # /etc/rc.conf, /etc/rc.conf.local or /etc/rc.conf.d/NAME # # NAME_enable="NO" # set to YES to enable openvpn
The startup script will also indicate if any additional parameters are available:
# NAME_if= # driver(s) to load, set to "tun", "tap" or "tun tap" # # it is OK to specify the if_ prefix. # # # optional: # NAME_flags= # additional command line arguments # NAME_configfile="/usr/local/etc/openvpn/NAME.conf" # --config file # NAME_dir="/usr/local/etc/openvpn" # --cd directory # # You also need to set NAME_configfile and NAME_dir, if the configuration # file and directory where keys and certificates reside differ from the above # settings.
Creating your own FreeNAS® PBIs
If a FreeNAS® PBI does not already exist for the software that you need, you can create your own PBI. This section describes the PBI architecture, then provides an example of creating a PBI.
Introduction to PBI Modules
The PBI (push button installer) architecture was created by Kris Moore for the PC-BSD project. It provides a mechanism for converting existing FreeBSD packages or ports (which are installed through the command line) into self-contained software packages that can be installed through a graphical interface. The FreeNAS® PBI architecture extends this functionality by integrating PBIs into the FreeNAS® graphical interface: making it easy to install, configure, and manage the installed software from a web browser.
In order to create a PBI, the software must already be ported to FreeBSD. The easiest way to confirm whether or not a FreeBSD port exists is to search for the software at FreshPorts.org. If a port does not exist, you can issue a port request at the PC-BSD Port Requests forum using these instructions. Alternately, if you have ported software before, the Porters Handbook contains detailed instructions for porting software to FreeBSD. A table of outstanding PBI requests can be found here.
NOTE: at this time, PC-BSD PBIs are based on FreeBSD 9.0 and FreeNAS® PBI's are based on FreeBSD 8.3. Due to ABI (application binary interface) differences between the FreeBSD 8.x and 9.x series, you can not convert an existing PC-BSD PBI into a FreeNAS® PBI. This will change once FreeNAS® is based on FreeBSD 9.0, which is expected to occur in late 2012.
Each PBI is based upon a module. A PBI module is simply a collection of files which control the contents of the PBI and how it integrates into the FreeNAS® GUI. Existing PBI modules can be found in the Plugins Examples page of the FreeNAS® code repository.
Table 8.10e summarizes the function of the files which are found in a FreeNAS® PBI module. In addition to these files, the resources/ directory of a PBI may contain additional files specific to the configuration of that PBI.
Table 8.10e: FreeNAS® PBI Module Components
| File Name | Description |
| resources/control | this script is used to start, stop, and get the status of the service; it also controls other files that define the configuration options that appear in the FreeNAS® GUI |
| resources/default.png | the icon used in the tree of the FreeNAS® GUI |
| resources/tweak-rcconf | adds or removes the plugin entry in /etc/rc.conf so that the service will automatically start if the FreeNAS® system is rebooted |
| scripts/post-install.sh | script run immediately after the extraction of PBI contents to disk |
| scripts/post-portmake.sh | optional; script run after the port compile is finished but before the PBI is packaged; typically used to add extra plugins or to compile additional ports not included in the port's Makefile |
| scripts/pre-install.sh | optional; script run to check conditions before the installation of the PBI (e.g. check for minimum FreeNAS® version) |
| scripts/pre-remove.sh | optional; script run before deletion of the PBI file; typically used to make sure the service has been stopped, to remove log or temporary files used by the software, or to delete a system account used by the software being deinstalled |
| pbi.conf | similar to a FreeBSD port's Makefile, this file contains the instructions for compiling the PBI; the variables in this file are documented in the PBI Module Builder Guide |
Once you have verified that a FreeBSD port exists, you can create the PBI module from within a FreeNAS® Plugins Jail. If this is your first PBI module, it is recommended that you install an existing PBI and compare the configuration options that you see in the FreeNAS® GUI with the files in that PBI's module. This will give you an idea of how to edit the files to match the needs of the software that you are creating a PBI for.
A summary of the steps needed to create a PBI is as follows:
1. If you haven't already, install and start the Plugins Jail. The rest of the commands in this section need to be executed from within the jail.
2. Download the FreeBSD ports tree.
3. Create the directory structure to contain the PBI module.
4. Download the plugin example files (recommended).
5. Create the files used by the PBI module.
6. Run the pbi_makeport command.
7. Install the PBI to verify that it installs, contains the desired configuration options in the GUI, and that the service is able to start.
The next section will demonstrate steps 2-7. When creating your own PBI, modify the example to match the needs of the specific application.
Download Ports and Create the PBI Module Directory
Since a PBI is based on a FreeBSD port (an application that has been ported to FreeBSD), you will need to install the FreeBSD ports collection before you can build your PBI. The following commands are used to determine the Plugins Jail ID, enter the jail, and install the ports collection:
jls JID IP Address Hostname Path 1 - software /mnt/volume1/jail/software jexec 1 /bin/tcsh software# portsnap fetch extract Fetching public key from portsnap.FreeBSD.org... done. Fetching snapshot tag from portsnap.FreeBSD.org... done. Fetching snapshot metadata... done. Fetching snapshot generated at Tue Jul 17 00:01:37 UTC 2012: <snip> Building new INDEX files... done.
Next, create the directory structure to contain the PBI module. When making your directory structure, use the name of the port that you are converting to a PBI. For example, if you are creating a PBI for bacula-bat, create a directory called bacula-bat. A good place to make this directory is in a subdirectory of /usr/local. In this example, all PBI modules are created in /usr/local/my_pbis/, /usr/local/my_pbis/openvpn/ holds the files used by the openvpn PBI module, and -p is used to make any missing subdirectories in the path to the directory.
mkdir -p /usr/local/my_pbis/openvpn/resources mkdir -p /usr/local/my_pbis/openvpn/scripts
Next, create the files listed in Table 8.10e. The easiest way to do this is to modify the files in an existing PBI module to meet the needs of the software being converted into a PBI. You can find existing PBI modules here. As each file is reviewed in this example, the sections of text that should be modified are listed in red text.
NOTE: at this time, it is not possible to paste into the Plugins Jail. For this reason, we recommend that you download the existing example plugins so that you can refer to them and copy existing files into your PBI's directory structure in order to edit them for the PBI that you are creating.
The easiest way to obtain the most current copy of the example plugins directory is to use the svn co command. This command requires you to install the subversion port. The following example installs the port then copies the example plugins directory structure into /usr/local/my_pbis/.
cd /usr/ports/devel/subversion make install clean (press tab then enter whenever a configuration menu is displayed) rehash cd /usr/local/my_pbis svn co https://freenas.svn.sourceforge.net/svnroot/freenas/branches/8.3.0/nanobsd/plugins/ Error validating server certificate for 'https://freenas.svn.sourceforge.net:443': - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: *.svn.sourceforge.net - Valid: from Sat, 25 Feb 2012 23:58:41 GMT until Sun, 31 Mar 2013 19:51:44 GMT - Issuer: GeoTrust, Inc., US - Fingerprint: 0b:11:76:de:db:4c:74:72:cb:01:49:7d:13:70:c2:f1:13:7b:cb:bf (R)eject, accept (t)emporarily or accept (p)ermanently? p <snip download> Checked out revision 11909.
If you repeat the above cd and svn co commands whenever you create a new PBI, you will always have a copy of the latest plugin examples.
Create the Module Components
This section describes how to edit the module components required by any PBI. Depending upon the application's needs, you may also want to create some of the optional files listed in Table 8.10e. Start by creating the mandatory components, then decide if you wish to tweak the PBI further after testing it.
post-install.sh
Save this file in the scripts subdirectory of your PBI module. The following example uses a copy of the firefly file with descriptive comments added. When creating your file, replace any text in red with the name of the PBI.
cp /usr/local/my_pbis/plugins/firefly_pbi/scripts/post-install.sh /usr/local/my_pbis/openvpn/scripts/ more /usr/local/my_pbis/openvpn/scripts
The following lines are required for any PBI:
#!/bin/sh # replace red text with PBI name; path should be a subdir of /usr/pbi firefly_pbi_path=/usr/pbi/firefly-$(uname -m)/ # mandatory; required to integrate into FreeNAS GUI mkdir -p ${firefly_pbi_path}/mnt mkdir -p ${firefly_pbi_path}/www ${firefly_pbi_path}/bin/python ${firefly_pbi_path}/fireflyUI/manage.py syncdb --migrate --noinput
The following line is optional, depending upon the needs of the software.
# use if the service requires that the specified system account be created pw user add daapd -d ${firefly_pbi_path}
Some PBIs require the creation of directories with specific permissions set. The post-install.sh for the transmission and minidlna PBIs provide examples. If you receive permission errors when testing your PBI, research the permission and ownership required by those directories, add that information to this file, then rebuild the PBI and test it again.
tweak-rcconf
This file is used to add an entry to /etc/rc.conf when the PBI is installed and to remove that entry when the PBI is uninstalled. On a FreeBSD system, rc.conf is used to determine which services to start at boot time. An entry in this file is a requirement in order to start the PBI using Services → Control Services as the GUI sends the start option to the service's startup script.
Save this file in the the resources subdirectory for the PBI module, changing the text in red to the name of the service.
#!/bin/sh firefly_path=/usr/pbi/firefly-$(uname -m) tmpfile=$(mktemp /tmp/.XXXXXX) grep -v 'firefly_' /etc/rc.conf > ${tmpfile} cat ${fireflyy_path}/etc/rc.conf >> ${tmpfile} mv ${tmpfile} /etc/rc.conf
pbi.conf
pbi.conf is a shell script that contains the information needed to build the PBI. Typically this file only requires you to modify a few variables, such as the name of the program, its website, and its location in the ports tree. Sometimes you will need to set a few additional variables in order to make sure that required dependencies are included in the PBI. This file should be created in the root of your PBI module directory.
The following example is from the firefly PBI; edit the text in red to match the information for your PBI. You can determine the correct values by searching for the FreeBSD port at FreshPorts.org. Note that your file should not include the PBI_BUILDKEY or PBI_AB_PRIORITY variables as these are only used by the FreeNAS® build server.
#!/bin/sh # Program Name PBI_PROGNAME="firefly" # Program Website PBI_PROGWEB="http://www.fireflymediaserver.org/" # Program Author / Vendor PBI_PROGAUTHOR="Firefly" # Default Icon (Relative to %%PBI_APPDIR%% or resources/) PBI_PROGICON="default.png" # The target port we are building PBI_MAKEPORT="audio/firefly" # Additional options for make.conf PBI_MAKEOPTS="PACKAGE_BUILDING=Y" # Ports to build before / after PBI_MKPORTBEFORE="" PBI_MKPORTAFTER="www/py-django devel/py-jsonrpclib databases/py-south databases/py-sqlite3 www/py-dojango devel/py-jsonrpclib www/py-flup net/py-oauth2" # Exclude List PBI_EXCLUDELIST="./include ./share/doc"" export PBI_PROGNAME PBI_PROGWEB PBI_PROGAUTHOR PBI_PROGICON PBI_MAKEPORT PBI_MAKEOPTS PBI_MKPORTBEFORE PBI_MKPORTAFTER PBI_EXCLUDELIST
Table 8.10f summarizes the variables which can be included in this file.
Table 8.10f: pbi.conf Variables
| Variable | Description |
| PBI_PROGNAME= | mandatory; should be the same value as PORTNAME= in the port's Makefile |
| PBI_PROGWEB= | mandatory unless does not exist; should be the same value as WWW= in the port's pkg-descr |
| PBI_PROGAUTHOR= | mandatory; often found in the port's pkg-descr or at the website for the application |
| PBI_PROGICON= | specified icon must exist in resources/ of PBI module; must be a 64x64 .png file with a transparent background |
| PBI_PROGREVISION= | bump up a PBI's revision number; useful when rebuilding a port with new PBI specific options |
| PBI_MAKEPORT= | mandatory; the path to the port under /usr/ports/ |
| PBI_MAKEOPTS= | optional; set this to the options that you want saved into make.conf for the port building process (e.g. WITH_CUPS=YES) |
| PBI_MKPORTBEFORE= | optional; port(s) to build before starting the build for the target port |
| PBI_MKPORTAFTER= | optional; additional port(s) to build after building the target port |
| PBI_BUILDKEY= | should not be included; this variable is used on the PBI build server to force the rebuild of a PBI that has failed to build |
| PBI_REQUIRESROOT= | set to to YES to require this app to be installed as root; default is NO which allows it to be installed as a regular user |
| PBI_EXCLUDELIST= | list of files or directories to exclude from the final archive, such as ./include or ./share |
| PBI_AB_PRIORITY= | should only be set by build server administrator; a higher number indicates a greater priority and will be built before lower priority PBIs |
| export | mandatory; followed by a list of all of the variables used in the file |
default.png
This icon file will be used when the entry for the installed PBI is added to the FreeNAS® tree. The name of the icon is specified with the PBI_PROGICON= variable and that file must exist in the resources/ directory of the PBI module. If you decide to make your own icon, it must be a 64x64 .png file with a transparent background. Otherwise, copy the default.png file from the firefly PBI.
control
The FreeNAS® PBI API uses control to initialize the web interface for the installed plugin. The FreeNAS® GUI communicates with plugins using FastCGI; the role of the control file is to setup the FastCGI server.
The FastCGI API supports many programming languages, including Python and PHP. If you are comfortable using a supported programming language, you can create your own control file and use control as the wrapper pointing to your file. For example, the creator of the transmission PBI created control.py in Python to setup WSGI, the Python FastCGI interface. The creator of the minidlna PBI had the control file point to php-fpm.conf in order to configure php-fpm, the PHP FastCGI interface. If you are familiar with either of those languages, examine that PBI's control file and the rest of the files under that PBI's resources/ directory, comparing the content of those files to the resulting FreeNAS® screens shown in Popular PBIs.
The supported language bindings are listed here. Before selecting a language, you will need to research which bindings are required and build those FreeBSD ports with your PBI. For example, the firefly PBI uses Python and specifies the required bindings in its pbi.conf:
PBI_MKPORTAFTER="www/py-django devel/py-jsonrpclib databases/py-south databases/py-sqlite3 www/py-dojango devel/py-jsonrpclib www/py-flup net/py-oauth2"
NOTE: if you are not familiar with any of the supported programming languages and their bindings, you can still create a PBI without a control file. However, you will have to manually install it using the pbi_add command and it will not integrate into the FreeNAS® GUI. You may find it easier to install software using its FreeBSD package or port, unless your goal is to practice creating PBI software.
Create and Test the PBI
THIS SECTION IS STILL BEING TESTED, WHILE THE COMMANDS ARE CORRECT THEY DO NOT WORK YET IN THE PLUGINS JAIL
Once you have created the module components, you are ready to build and test the PBI. Typically you will build and test the PBI, make any adjustments to the module components to fine-tune the PBI, then repeat the build and test cycle until you are satisfied with the PBI.
Before building a PBI, make sure the following pre-requisites are met:
1. Double-check that the Ports Jail has enough space to perform the build. PBIs are built into a chroot which requires that the FreeBSD source tree be downloaded and placed in a temporary subdirectory of /usr/pbi/. This will fail if you don't have enough available space in the jail. The current source tree size is about 1.7GB.
2. Give the jail permission to mount the filesystems it needs in order to build a PBI. This command must be run outside the jail; in other words, type exit to leave the jail if you are in it and run the following command in Shell. Once finished, re-enter the jail.
sysctl security.jail.mount_allowed=1 security.jail.mount_allowed: 0 -> 1
3. The pbi_makeport command calls the make installworld command which will fail unless you edit /etc/make.conf to add the following line:
INSTALLFLAGS_EDIT= :S/-fschg//
4. If this is your first PBI build, create the directory to store the build log. On a 64-bit system, create the required directory using this command:
mkdir /usr/pbi/amd64
5. Build the required .pbiwrapper file with these commands:
svn co svn://svn.pcbsd.org/pcbsd/current/src-sh make make install
To build the PBI, use the built-in pbi_makeport command. cd into your module directory and specify the port to build. The following command will build the openvpn port and specify that the module in the current directory should be used and that the resulting PBI be placed in the same directory. The -k switch is included so that the build files can be reused should the PBI need to be rebuilt after testing. The & is included to start the build in the background so that the prompt is returned. To monitor the status of the PBI build on a 64-bit system, type tail -f /usr/pbi/amd64/.buildWorldLog.
cd /usr/local/my_pbis/openvpn pbi_makeport -c . -k -o . security/openvpn & Building the PBI chroot environment... This may take a while... Using svn://svn.freebsd.org/base/head for sources Assuming a BETA|RC or rarely used FreeBSD version. Using CURRENT! Checking out FreeBSD sources from svn://svn.freebsd.org/base/head Running buildworld / installworld
The first time you create a PBI, the chroot is built from scratch. This can take a significant amount of time (a few hours). Once the chroot is built, a copy of is saved before the actual PBI build begins. This means that the next time you build a PBI, a new chroot is created from the copy. This saves time (you do not have to build it again) while still ensuring that every PBI is built using a clean environment. If you need to leave Shell during the build process, use the X in the upper right corner to close shell so that the process remains running.
Once the chroot is available, the PBI build will start:
Extracting chroot environment...
Table 8.10g summarizes the options available to the pbi_makeport command.
Table 8.10g: pbi_makeport Options
| Switch | Description |
| -B | performs the build without creating the PBI |
| -c confdir | specify the PBI module directory |
| -d portsdir | specify an alternative ports directory to /usr/ports; ports collection must actually exist in specified directory |
| -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 the location where the PBI will be installed on the end-user's system |
| --delbuild | remove any existing build directories before starting the build |
| --mkdebug | will drop to a debugging shell should the port build fail |
| --tmpfs | can speed up port compiles on systems with lots of RAM |
| --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 | enable .txz package caching in the specified directory |
| --sign keyfile | digitally sign the PBI file with the specified openssl private key file |
Once you have finished testing your PBI submit it to the forums so that it is available for testing by other users.
