1
Tutorials and FAQs / Re: Making OPNsense more useful with custom-built packages
« on: February 26, 2021, 10:00:38 pm »
Part 4: Making things useful
Build cache
We've just installed ccache. Now we need to create a directory for it to use:
Ccache defaults to not use more than 5 GB of space for its cache. I doubt that it makes sense to increase it as repositories for OPNsense probably shouldn't be so big in the first place. On my FreeBSD systems I do increase it, though. If you are low on disk space, you can of course also lower the limit. I'm going to write out the default here for reference purposes:
To make Poudriere use ccache, we have to edit its configuration again:
Find the "CCACHE_DIR=" line, comment it in and change it to:
Now we're going to add Poudriere to the list of packages to build so that we will get updates in the future:
Additional packages
Also add the programs that you actually wanted to build. To do so, simply put them into the package list file one per line and specify the programs as "category/name". My example here is the jail manager / virtualization framework cbsd.
You probably don't know the category if you're not working with ports regularly. You can use the "whereis" command to find out if you know the program's name:
So it would be "sysutils/cbsd" that needs to be added to the package list file:
But what if you are looking for something but don't even know the exact name of the program? The easiest thing is probably to use this website:
https://www.freshports.org
To the right you will find a "search" box that you can use. Explore the site a little, it is very useful if you are working with FreeBSD ports.
When you are happy with your package list, simply invoke the bulk build command again to make Poudriere build the missing packages:
Package repositories
Last time we used "pkg add" to install the ccache package manually. While there's nothing really wrong with that, this method is less helpful if you want to keep your system up to date. This is where repositories come into play. A repository is a set of package files with additional metadata to e.g. make it searchable. Don't worry about the details - Poudriere takes care of all that for you. You only need to make the package manager aware of your additional repository. We'll do that now. Let's take a look at a configuration example:
Pretty simple, eh? This is an override config that disables the repository called "FreeBSD" which comes with the operating system and is otherwise enabled by default. Have a look at the file OPNsense.conf if you are curious.
Now create a new file:
And paste the following into it:
This will configure a new repository called "Custom" for pkg to use. I'm setting a lower priority than the OPNsense repository has by default. Why? Because we want the official packages to take precedence to not break anything. If you plan on building your packages often, the cleanest solution would be add all required packages to your list and to disable the OPNsense repository completely.
When using multiple repositories you might run into the situation where pkg will not update to newer packages in your repository even if you give it a higher priority. This is due to the (default) option called "CONSERVATIVE_UPGRADE": pkg remembers which repository a package was originally installed from and will generally prefer that repository over others. Edit /usr/local/etc/pkg.conf and switch that option off if you want to go that route.
Now make the package manager read the repository information again:
After the previous step, I can simply install my jail manager:
There we go! It will ask me to confirm the actions that it is about to take and a couple of seconds later the program that is not packaged by OPNsense is installed cleanly on the system.
Build options
FreeBSD's ports framework allows for customizing build-time options for many packages. You can issue the following command to configure all of the ports in your list (AND their dependencies!):
Doing so is not much fun. HardenedBSD added hardening options to each and every port, even those that don't have any options on vanilla FreeBSD - and OPNsense inherited this. So for all the ports potentially involved this will display a configuration menu for you. Most of the time you will probably just hit Enter but you might want to actually customize a couple of ports. Seriously, this is pretty tedious. Cbsd is not an extreme example at all, but look how much configuration dialogs it caused:
A better way might be to configure only the ports that you are interested in customizing. While cbsd doesn't in fact currenly have any interesting build-time options to tweak, we're going to do it anyway here for demonstration purposes. Here's how to do it:
This will bring up the configuration menu and if you confirm the selection, the options get saved. By default, the ports tree will save its options in /var/db/ports. There should be a "sysutils_cbsd" directory inside now. You can simply copy those over for use by Poudriere:
That way you can configure only the ports that you actually care about and not potentially hundreds of others as well.
Updating
Staying safe means regularly upgrading the system. How do you do it? The first step is updating the ports tree. Do this by issuing:
Step two is to simply start another bulk build the way you've done at least twice now. When Poudriere has finished you will have a repository with fresh packages in it. You can either update via the command line by issuing:
Or you simply use the GUI as you're used to. It will show the updates from all configured repositories, so you don't even have to remember how to use pkg.
Have fun with your new even more useful OPNsense box(es) and enjoy a great Open Source project!
What now?
I still have a couple of things on my mind that I could put into another post - mostly ideas to make this whole procedure easier for users. But with these 4 parts people should be able to roll their own packages. So before putting more time and effort into this, I'll wait to see if this tutorial is actually useful to anybody.
Feel free to ask if you have questions about this. Of course comments or suggestions are welcome as well.
Build cache
We've just installed ccache. Now we need to create a directory for it to use:
Code: [Select]
# mkdir -p /var/cache/ccache/poudriere
Ccache defaults to not use more than 5 GB of space for its cache. I doubt that it makes sense to increase it as repositories for OPNsense probably shouldn't be so big in the first place. On my FreeBSD systems I do increase it, though. If you are low on disk space, you can of course also lower the limit. I'm going to write out the default here for reference purposes:
Code: [Select]
# echo max_size = 5.0G > /var/cache/ccache/poudriere/ccache.conf
To make Poudriere use ccache, we have to edit its configuration again:
Code: [Select]
# vi /usr/local/etc/poudriere.conf
Find the "CCACHE_DIR=" line, comment it in and change it to:
Code: [Select]
CCACHE_DIR=/var/cache/ccache/poudriere
Now we're going to add Poudriere to the list of packages to build so that we will get updates in the future:
Code: [Select]
# echo ports-mgmt/poudriere >> /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-pkglist
Additional packages
Also add the programs that you actually wanted to build. To do so, simply put them into the package list file one per line and specify the programs as "category/name". My example here is the jail manager / virtualization framework cbsd.
You probably don't know the category if you're not working with ports regularly. You can use the "whereis" command to find out if you know the program's name:
Code: [Select]
# whereis cbsd
cbsd: /usr/ports/sysutils/cbsd
So it would be "sysutils/cbsd" that needs to be added to the package list file:
Code: [Select]
# echo sysutils/cbsd >> /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-pkglist
But what if you are looking for something but don't even know the exact name of the program? The easiest thing is probably to use this website:
https://www.freshports.org
To the right you will find a "search" box that you can use. Explore the site a little, it is very useful if you are working with FreeBSD ports.
When you are happy with your package list, simply invoke the bulk build command again to make Poudriere build the missing packages:
Code: [Select]
# poudriere bulk -j opnsense211 -p opnports -z customsense -f /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-pkglist
Package repositories
Last time we used "pkg add" to install the ccache package manually. While there's nothing really wrong with that, this method is less helpful if you want to keep your system up to date. This is where repositories come into play. A repository is a set of package files with additional metadata to e.g. make it searchable. Don't worry about the details - Poudriere takes care of all that for you. You only need to make the package manager aware of your additional repository. We'll do that now. Let's take a look at a configuration example:
Code: [Select]
# cat /usr/local/etc/pkg/repos/FreeBSD.conf
FreeBSD: { enabled: no }
Pretty simple, eh? This is an override config that disables the repository called "FreeBSD" which comes with the operating system and is otherwise enabled by default. Have a look at the file OPNsense.conf if you are curious.
Now create a new file:
Code: [Select]
# vi /usr/local/etc/pkg/repos/custom.conf
And paste the following into it:
Code: [Select]
Custom: {
url : file:///usr/local/poudriere/data/packages/opnsense211-opnports-customsense,
priority : 20,
enabled : yes
}
This will configure a new repository called "Custom" for pkg to use. I'm setting a lower priority than the OPNsense repository has by default. Why? Because we want the official packages to take precedence to not break anything. If you plan on building your packages often, the cleanest solution would be add all required packages to your list and to disable the OPNsense repository completely.
When using multiple repositories you might run into the situation where pkg will not update to newer packages in your repository even if you give it a higher priority. This is due to the (default) option called "CONSERVATIVE_UPGRADE": pkg remembers which repository a package was originally installed from and will generally prefer that repository over others. Edit /usr/local/etc/pkg.conf and switch that option off if you want to go that route.
Now make the package manager read the repository information again:
Code: [Select]
# pkg update
After the previous step, I can simply install my jail manager:
Code: [Select]
# pkg install cbsd
There we go! It will ask me to confirm the actions that it is about to take and a couple of seconds later the program that is not packaged by OPNsense is installed cleanly on the system.
Build options
FreeBSD's ports framework allows for customizing build-time options for many packages. You can issue the following command to configure all of the ports in your list (AND their dependencies!):
Code: [Select]
# poudriere options -j opnsense211 -p opnports -z customsense -f /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-pkglist
===> Setting user-specified options for cbsd-13.0.0 and dependencies
Doing so is not much fun. HardenedBSD added hardening options to each and every port, even those that don't have any options on vanilla FreeBSD - and OPNsense inherited this. So for all the ports potentially involved this will display a configuration menu for you. Most of the time you will probably just hit Enter but you might want to actually customize a couple of ports. Seriously, this is pretty tedious. Cbsd is not an extreme example at all, but look how much configuration dialogs it caused:
Code: [Select]
# ls /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-options/| wc -l
275
A better way might be to configure only the ports that you are interested in customizing. While cbsd doesn't in fact currenly have any interesting build-time options to tweak, we're going to do it anyway here for demonstration purposes. Here's how to do it:
Code: [Select]
# make -C /usr/ports/sysutils/cbsd config
This will bring up the configuration menu and if you confirm the selection, the options get saved. By default, the ports tree will save its options in /var/db/ports. There should be a "sysutils_cbsd" directory inside now. You can simply copy those over for use by Poudriere:
Code: [Select]
# mkdir -p /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-options
# cp -r /var/db/ports/* /usr/local/etc/poudriere.d/opnsense211-opnports-customsense-options/
That way you can configure only the ports that you actually care about and not potentially hundreds of others as well.
Updating
Staying safe means regularly upgrading the system. How do you do it? The first step is updating the ports tree. Do this by issuing:
Code: [Select]
# cd /usr/ports && git pull && cd -
Step two is to simply start another bulk build the way you've done at least twice now. When Poudriere has finished you will have a repository with fresh packages in it. You can either update via the command line by issuing:
Code: [Select]
# pkg upgrade
Or you simply use the GUI as you're used to. It will show the updates from all configured repositories, so you don't even have to remember how to use pkg.
Have fun with your new even more useful OPNsense box(es) and enjoy a great Open Source project!
What now?
I still have a couple of things on my mind that I could put into another post - mostly ideas to make this whole procedure easier for users. But with these 4 parts people should be able to roll their own packages. So before putting more time and effort into this, I'll wait to see if this tutorial is actually useful to anybody.
Feel free to ask if you have questions about this. Of course comments or suggestions are welcome as well.