3 | FreeBSD Foundation

How to use VS Code on FreeBSD

Anne Dickison — Fri, 10 May 2024 16:00:38 +0000

Visual Studio Code (VS Code) is a source-code editor developed by Microsoft for Windows, Linux, and macOS. Through the extensive work of the FreeBSD community, it has also been ported to FreeBSD and can be installed through binary packages. Setting up VS Code is simple and quick, and can be done from a fresh FreeBSD install.

Requirements:

FreeBSD running on amd64 architecture

A desktop environment (Refer to this guide to set up XFCE on your system)

Installation and Configuration:

Install the VS Code binary package:

$ su

# pkg install vscode

Note: As of this guide being written, Electron is blacklisted from the package builder. As this is a dependency of the vscode package, this may mean you will have to build VS Code from the ports collection:

# pkg install git

# git clone https://git.FreeBSD.org/ports.git /usr/ports

# git -C /usr/ports pull

# cd /usr/ports/editors/vscode

# make install clean

Exit the su root shell:

# exit

VS Code can be run directly from the terminal:

$ vscode

Additional language extensions can be installed directly through the VS Code application. Browse the available options through the “Extensions” button on the left of the client.

Note: Check the file locations where VS Code is configured to find them. rust-analyzer, for instance, will give an error because the VS Code extension searches a different file than where it is stored on FreeBSD. To quickly fix this issue:

$ whereis rust-analyzer 

rust-analyzer: /usr/local/bin/rust-analyzer

Navigate to the VSCode settings gear in the bottom left and open the .json settings file.

Add the correct path to the rust binary:
“rust-analyzer.server.path”: “/usr/local/bin/rust-analyzer”

Using VS Code:

Let’s use VS Code to create a simple “hello world” script using Python:

Start by creating and opening a folder, either using the dropdown menu under ‘File’ or on the welcome page. Click “Create Folder” at the top right of the client. We’ll store the text files we create here. Once opened, VS Code will show the empty folder in the “Explorer” section.

Create a new file in this folder, VS Code will ask for either a file type or file name. In this example, I named it PythonTest.py.

VS Code will correctly identify the file as Python, but further support will be needed to provide IntelliSense (code auto-completion and quick info), formatting, and debugging.

Navigate to the ‘Extensions’ tab on the left of the client, and install the ‘Python’ language support extension.

Now when we try to type a simple print command in the Python file we created, VS Code will autocomplete and show error messages

Type a simple hello world command:

Save your changes under ‘File’.

Tip: Enable ‘Auto Save’ so you don’t have to manually save each time changes are made.

Then, run and debug the file. Either by pressing ‘F5’ or selecting ‘Run Python File’ at the top right of the client.

Troubleshooting VS Code:

While this guide aims to be as broad as possible, users may still run into issues when installing the vscode package. There’s a wide range of possible errors, from unsupported packages to known bugs to unsupported hardware.

Note: The vscode port is currently only supported for the amd64 architecture; if you run into an error mentioning unsupported architecture, confirm that the system is amd64:

$ uname -a

1. Search the Problem Report (PR) database for known fixes pending implementation. This is also useful to find existing bugs that other users have encountered.

2. If none of the above works, contact the port maintainer directly. Port maintainers are listed at the top of the FreshPorts page. An easy way to get visibility on an issue is to post to the freebsd-ports mailing list and CC the maintainer. Ask if they know of any issues and include the output before the error.

The post How to use VS Code on FreeBSD first appeared on FreeBSD Foundation.

An Introduction to Packet Filter (PF)

Anne Dickison — Tue, 12 Sep 2023 19:35:40 +0000

Packet Filter, also known as PF or pf, is a BSD-licensed stateful packet filter used to filter TCP/IP traffic and perform Network Address Translation (NAT.) Originally created by OpenBSD, PF has been ported to FreeBSD since 5.3-RELEASE.

PF can identify where a packet should be directed or if it should even be allowed through; this can be decided based on the source and destination of that individual packet. PF can detect and block traffic you want to keep out of or in the local network. The firewall is highly flexible and even offers bandwidth management and packet priority.

1 . Enabling PF

PF relies on its kernel module, this must be enabled through /etc/rc.conf to start PF:

# sysrc pf_enable=yes
Additional options can be enabled when PF is started, this can be done by adding the following line to /etc/rc.conf. Required flags can later be specified between the two quotes(“”):

pf_flags="" # additional flags for pfctl startup

To start, PF will need to find its ruleset configuration file. FreeBSD does not ship with a ruleset or /etc/pf.conf. Custom rulesets can be used by specifying the path in /etc/rc.conf

pf_rules="/path/to/pf.conf"

Logging support for PF is provided by pflog(4). To enable logging support, add pflog_enable=yes to /etc/rc.conf:

# sysrc pflog_enable=yes

The following lines can also be added to change the default location of the log file or to specify any additional flags to pass to pflog(4) when it is started:

pflog_logfile="/var/log/pflog" # where pflogd should store the logfile
pflog_flags="" # additional flags for pflogd startup

The following option will enable NAT if there is a LAN behind the firewall:

gateway_enable="YES"

PF can now be started with logging support:

# service pf start
# service pflog start

2. Using pfctl

PF can be controlled using pfctl, refer to pfctl(8) for a description of all available options. Here are some of the more common pfctl options:

`pfctl -e`	Enable PF.
`pfctl -d`	Disable PF.
`pfctl -F all -f /etc/pf.conf`	Flush all NAT, filter, state, and table rules and reload `/etc/pf.conf.`
`pfctl -s [ rules \| nat \| states ]`	Report on the filter rules, NAT rules, or state table.
`pfctl -vnf /etc/pf.conf`	Checks `/etc/pf.conf` for errors, but does not load ruleset.

3. Creating a Base PF Ruleset

PF depends on a ruleset, which can be customized to best serve any system. Creating a base ruleset is the first step in customizing your firewall that can be further augmented and specified. Create the ruleset in

Start by creating a simple ruleset that applies to only a single machine, relies on one network, and does not run services:

block in all

pass out all keep state

This rule will deny all incoming traffic, while the second rule allows connections created by this system to pass out while retaining state information on those connections. Load this new ruleset with the following:

# pfctl -e ; pfctl -f /etc/pf.conf

In addition to keeping state, PF provides lists and macros that can be defined when creating rules. Macros can include lists and need to be defined before use. As an example, insert these lines at the very top of the ruleset:

tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }"

udp_services = "{ domain }"

PF can use port names and numbers if the names are listed in /etc/services. In this example, all traffic is blocked except for the connections initiated by this system for the seven specified TCP services and the one specified UDP service:

tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }"
udp_services = "{ domain }"
block all pass out proto tcp to any port $tcp_services keep state
pass proto udp to any port $udp_services keep state

Next, at the top of your ruleset, create a set skip rule for the loopback device because it does not need to filter traffic and would likely bring your server to a crawl.

set skip on lo0

Finally, add a pass out inet rule for the ICMP protocol, which allows you to use the ping(8) utility for troubleshooting

pass out inet proto icmp icmp-type { echoreq }

The ruleset should now resemble the following:

set skip on lo0
tcp_services = "{ ssh, smtp, domain, www, pop3, auth, pop3s }"
udp_services = "{ domain }"
block all
pass out proto tcp to any port $tcp_services keep state
pass proto udp to any port $udp_services keep state
pass out inet proto icmp icmp-type { echoreq }

After each edit, the ruleset needs to be loaded again:

# pfctl -f /etc/pf.conf

pfctl will not output any messages unless there are syntax errors that will need to be fixed. During the rule load, instead of loading the ruleset, a test can be run with:

# pfctl -nf /etc/pf.conf

Including -n causes the rules to be interpreted only but not loaded. This provides an opportunity to correct any errors. The last valid ruleset loaded will be enforced until either PF is disabled or a new ruleset is loaded.

4. Testing Your Base Ruleset

Testing your ruleset between major edits is crucial to ensure that PF functions properly.

First test for internet connectivity and DNS service:

# ping -c 3 google.com

Check that the pkgs repository can be reached:

# pkg upgrade

And finally, reboot:

# reboot

Give your server a few minutes to reboot. Next, you will expand the ruleset with more advanced features to see some possible applications of the PF ruleset.

5. Example Rulesets and Their Application

Now that you have created a base ruleset, the base ruleset can be built upon for more advanced PF functions. While this guide won’t cover every possible function or customization, these basic rulesets may be helpful for your system, or offer insight into how PF may be used. After each example, make sure to test the base ruleset.

5.1 Blocking Spoofed Packets

Address spoofing is a method where an outside user forges the source IP of sent packets to conceal the actual address, essentially impersonating another internet node. This opens the door for a network attack that does not disclose where it’s originating.

The antispoof PF keyword can help protect against spoof packets:

antispoof [log] [quick] for interface [af]

log: Specifies that packets matching the criteria should be reported by pflogd (8).
quick: This ensured that if a packet meets this rules, examination of the ruleset will cease.
interface: Specify the specific network where spoofing protection will be activated.
af: Address family (i.e., inet or inet6 for IPv4 and IPv6)

The most basic way to weed out spoofed traffic coming in from external sources, as well as any spoofed packets that originate in the local network:

antispoof for $ext_if
antispoof for $int_if

5.2 Protecting SSH Ports

A typical exploit is to target SSH ports, which are open to the public. This is often done with brute force attacks and can succeed if the server has weak passwords. PF has built-in features that help deal with brute-force attacks. PF can limit the simultaneous connection attempts a single host allows. Once a host exceeds this number, the connection will be dropped, and they will be banned from the server. PF’s overload mechanism has a table of banned IP addresses.

Modify your previous base ruleset to limit simultaneous connections from a single host:

pass in on $vtnet0 proto tcp to port { 22 } \

keep state (max-src-conn 15, max-src-conn-rate 3/1, \

overload flush global)

keep state: Allows you to define the state criteria for the overload table.
max-src-conn: Specifies the number of simultaneous connections allowed from a single host per second.
max-src-conn-rate: Specifies the number of new connections allowed from a single host per second.

If any host exceeds the specified limits, the PF overload mechanism will add the source IP to the table. If a host exceeds these limits, the overload mechanism adds the source IP to the table, which bans them from the server. The connection will immediately be dropped due to the flush global parameter.

Before this ruleset can be loaded, the table you defined needs to be declared in the ruleset:

Specify the table underneath the previous icmp_types macro

icmp_types = "{ echoreq }"

table persist

The persist keyword allows an empty table to exist in the ruleset. Without it, PF will complain that there are no IP addresses in the table.

5.3 Handling Non-Routable Addresses

As much as you can properly configure your system to be precise, some configuration may be needed to compensate for other people’s misconfigurations. One common mistake is to let traffic with non-routable addresses out to the Internet. Since non-routable addresses can be used in DoS attacks, consider blocking this traffic from entering the network.

Define a macro containing non-routable addresses, then use it in blocking rules. Traffic to and from these addresses is dropped on the gateway’s external interface.

external = "{ 127.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, \
10.0.0.0/8, 169.254.0.0/16, 192.0.2.0/24, \
0.0.0.0/8, 240.0.0.0/4 }"

block drop in quick on $ext_if from $external to any
block drop out quick on $ext_if from any to $external

6. Viewing PF Logs

To view PF logs:

tcpdump -n -e -ttt -r /var/log/pflog

To view logs in real-time from the pflog0 interface, run the following command:

tcpdump -n -e -ttt -i pflog0

The pftop utility is a tool for quickly viewing firewall activity in real-time; it can be installed and started with:

pkg install pftop

pftop

The post An Introduction to Packet Filter (PF) first appeared on FreeBSD Foundation.

An Introduction to ZFS

Anne Dickison — Sun, 22 Jan 2023 15:20:05 +0000

ZFS combines the roles of volume manager and independent file system into one, giving multiple advantages over a stand-alone file system. It is renowned for speed, flexibility, and, most importantly, taking great care to prevent data loss. While many traditional file systems had to exist on a single disk at a time, ZFS is aware of the underlying structure of the disks and creates a pool of available storage, even on multiple disks. The existing file system will grow automatically when extra disks are added to the pool, immediately becoming available to the file system.

Getting Started

FreeBSD can mount ZFS pools and datasets during system initialization. To enable it, add this line to /etc/rc.conf:

zfs_enable="YES"

Then start the service:

# service zfs start

Identify Hardware

Before setting up ZFS, identify the device names of the disk associated with the system. A quick way of doing this is with:

# egrep 'da[0-9]|cd[0-9]' /var/run/dmesg.boot

The output should identify the device names, examples throughout the rest of this guide will use the default SCSI names: da0, da1, and da2. If the hardware differs, make sure to use the correct device names instead.

Creating a Single Disk Pool

To create a simple, non-redundant pool using a single disk device:

# zpool create example /dev/da0

To create files for users to browse within the pool:

# cd /example
# ls
# touch testfile

The new file can be viewed using ls:

# ls -al

We can already start using more advanced ZFS features and properties. To create a dataset within the pool with compression enabled:

# zfs create example/compressed
# zfs set compression=on example/compressed

The example/compressed dataset is now a ZFS compressed file system.

Disable compression with:

# zfs set compression=off example/compressed

To unmount a file system, use zfs umount and then verify with df:

# zfs umount example/compressed
# df

Verify that example/compressed is not included as a mounted file under the output.

The file system can be re-mounted with zfs:

# zfs mount example/compressed
# df

With the file system mounted, the output should include a line similar to the one below:

example/compressed 17547008 0 17547008 0% /example/compressed

ZFS datasets are created just like any other file system, the following example creates a new file system called data:

# zfs create example/data

Use df to see the data and space usage (some of the output has been removed for clarity)

# df
                                 . . . 
example/compressed  17547008       0 17547008     0%    /example/compressed
example/data        17547008       0 17547008     0%    /example/data

Because these file systems are built on ZFS, they draw from the same pool for storage. This eliminates the need for volumes and partitions that other file systems rely on.

To destroy the file systems and then the pool that is no longer needed:

# zfs destroy example/compressed
# zfs destroy example/data
# zpool destroy example

RAID-Z

RAID-Z pools require three or more disks but offer protection from data loss if a disk were to fail. Because the ZFS pools can use multiple disks, support for RAID is inherent in the design of the file system

To create a RAID-Z pool, specifying the disks to add to the pool:

# zpool create storage raidz da0 da1 da2

With the zpool created, a new file system can be made in that pool:

# zfs create storage/home

Enable compression and store an extra copy of directories and files:

# zfs set copies=2 storage/home
# zfs set compression=gzip storage/home

A RAID-Z pool is a great place to store crucial system files, such as the home directory for users. To make the file system the home new home directory :

# cp -rp /home/* /storage/home
# rm -rf /home /usr/home
# ln -s /storage/home /home
# ln -s /storage/home /usr/home

File system snapshots can be created to roll back to later, the snapshot name is marked in red and can be whatever you want:

# zfs snapshot storage/home@11-01-22

ZFS creates snapshots of a dataset, allowing users to back up a file system for roll backs or data recovery in the future.

# zfs rollback storage/home@11-01-22

To list all available snapshots, zfs list can be used:

# zfs list -t snapshot storage/home

Recovering RAID-Z

Every software RAID has a method of monitoring its state. View the status of RAID-Z devices using:

# zpool status -x

If all pools are Online and everything is normal, the message shows:

all pools are healthy

If there is a problem, perhaps a disk being in the Offline state, the pool state will look like this:

  pool: storage
 state: DEGRADED
status: One or more devices has been taken offline by the administrator.
	Sufficient replicas exist for the pool to continue functioning in a
	degraded state.
action: Online the device using 'zpool online' or replace the device with
	'zpool replace'.
 scrub: none requested
config:

	NAME        STATE     READ WRITE CKSUM
	storage     DEGRADED     0     0     0
	  raidz1    DEGRADED     0     0     0
	    da0     ONLINE       0     0     0
	    da1     OFFLINE      0     0     0
	    da2     ONLINE       0     0     0

errors: No known data errors

“OFFLINE” shows the administrator took da1 offline using:

# zpool offline storage da1

Power down the computer now and replace da1. Power up the computer and return da1 to the pool:

# zpool replace storage da1

Next, check the status again, this time without -x to display all pools:

# zpool status storage
 pool: storage
 state: ONLINE
 scrub: resilver completed with 0 errors on Fri Nov 4 11:12:03 2022
config:

	NAME        STATE     READ WRITE CKSUM
	storage     ONLINE       0     0     0
	  raidz1    ONLINE       0     0     0
	    da0     ONLINE       0     0     0
	    da1     ONLINE       0     0     0
	    da2     ONLINE       0     0     0

errors: No known data errors

Data Verification

ZFS uses checksums to verify the integrity of stored data, these data checksums can be verified (which is called scrubbing) to ensure integrity of the storage pool:

# zpool scrub storage

Only one scrub can be run at a time due to the heavy input/output requirements. The length of the scrub depends on how much data is store in the pool.After scrubbing completes, view the status with zpool status:

# zpool status storage
 pool: storage
 state: ONLINE
 scrub: scrub completed with 0 errors on Fri Nov 4 11:19:52 2022
config:

	NAME        STATE     READ WRITE CKSUM
	storage     ONLINE       0     0     0
	  raidz1    ONLINE       0     0     0
	    da0     ONLINE       0     0     0
	    da1     ONLINE       0     0     0
	    da2     ONLINE       0     0     0

errors: No known data errors

Displaying the completion date of the last scrubbing helps decide when to start another. Routine scrubs help protect data from silent corruption and ensure the integrity of the pool.

ZFS Administration

ZFS has two main utilities for administration: The zpool utility controls the operation of the pool and allows adding, removing, replacing, and managing disks. The zfs utility allows creating, destroying, and managing datasets, both file systems and volumes.

While this introductory guide won’t cover ZFS administration, you can refer to zfs(8) and zpool(8) for other ZFS options.

Further Resources

The post An Introduction to ZFS first appeared on FreeBSD Foundation.

Video Playback on FreeBSD – Quick Guide

Anne Dickison — Thu, 01 Sep 2022 20:26:36 +0000

In this guide, we’ll use the xine video player to set up basic video playback on a fresh FreeBSD install. The xine multimedia player relies on the XWindow system and the XVideo extension to provide a graphical video playback interface.

System Requirements:

Xorg supports a wide variety of video cards, but not all are supported or offer good video playback performance.

It is a good idea to have a short MPEG test file for evaluating various players and options. Since some DVD applications look for DVD media in /dev/dvd by default, or have this device name hardcoded in them, it might be useful to make a symbolic link to the proper device:

# ln -sf /dev/cd0 /dev/dvd

Due to the nature of devfs(5), manually created links will not persist after a system reboot. In order to recreate the symbolic link automatically when the system boots, add the following line to /etc/devfs.conf:

link cd0 dvd

Installing Xorg

There are several possible ways to display video under Xorg and what works is largely hardware dependent. This guide will focus on the Xvideo extension which allows video to be directly displayed, even on low-end machines.

Start by installing the X Window System:

# pkg install -y xorg

Once the package has been fully installed, the X Window System can be started with:

# startx

XVideo Support

To check whether the Xvideo extension is running, use xvinfo:

xvinfo

If XVideo is supported, the result will look similar to the example below and may include screen and video card information.

X-Video Extension version 2.2
  screen #0
  Adaptor #0: "Example Engine"
    number of ports: 1
    port base: 43
     
       .   .    .

XVideo is likely unsupported by the video card if the result instead look like:

X-Video Extension version 2.2
screen #0
no adaptors present

The display may be unable to meet the demands of rendering video playback if XVideo is unsupported (though this is not always the case).

The xine Video Player

xine is a free multimedia player. It plays back CDs, DVDs, BluRays and VCDs. It also decodes multimedia files like AVI, MOV, WMV, and MP3 from local disk drives, and displays multimedia streamed over the Internet. Get started by installing the package:

# pkg install -y xine

In practice, xine requires either a fast CPU or support for the XVideo extension. The xine video player performs best on XVideo interfaces. If in the previous step, the Xvideo extension was unsupported, issues may occur.

The xine player starts a graphical user interface (GUI) and the menus can be used to navigate to multimedia files.

# xine

Alternatively, xine may be directly invoked from the command line by specifying the name of the file to play:

# xine -g -p mymovie.avi

You now have a simple way to play a variety of multimedia files on your FreeBSD system! To find out more about the xine player, refer to the SourceForge page.

The post Video Playback on FreeBSD – Quick Guide first appeared on FreeBSD Foundation.

An Introduction to FreeBSD Jails

Anne Dickison — Mon, 15 Aug 2022 18:29:21 +0000

What are Jails?

Jails were developed as a tool for system administrators to enhance the security of a FreeBSD system. Originally introduced in FreeBSD 4.0, jails continue to be an integral part of the development and progression of the FreeBSD operating system.

Jails were created to expand upon the chroot(2) concept, which is used to change the root directory of a set of processes. Jails create a safe environment independent from the rest of the system. Processes created in this environment cannot access files or resources outside of it. For this reason, compromising a service running in a jail will not compromise the entire system. Jails improved upon the chroot(2) concept by virtualizing access to the file system, users, and the networking subsystem.

A jail is characterized by four elements:

A directory subtree: the starting point from which a jail is entered. Once inside the jail, a process is not permitted to escape outside of this subtree.
A hostname: which will be used by the jail.
An IP address: which is assigned to the jail. The IP address of a jail is often an alias address for an existing network interface.
A command: the path name of an executable to run inside the jail.

While the theory is very simple and straightforward, it is important to note that creating a jail can quickly become extremely complex while leveraging systems and tools within the environment.

Note: Jails have their own set of users and their own root account which are limited to the jail environment. The root account of a jail is not allowed to perform operations to the system outside of the associated jail environment.

Examples of Jails

Jails are often used as test environments. Running a service or software in a jail allows developers to isolate and test updates or changes without jeopardizing the integrity of the rest of the system. This mitigates the risk of misconfiguration or mistakes. Developers also have the ability to run multiple instances or configurations at the same time without influencing each separate jailed process.

In larger, more complex systems, jails can be used to split the system into separate jailed processes. Each jail could contain it’s own utilities and configurations, allowing for a much more streamlined system for specific tasks. Extremely complex processes can also be isolated to a jail, separate from the main system.

A Jail can be used as a container for an old system, preserving critical infrastructure either as a backup, or as a way of referring to old code, all contained within a new system. This way, the old system can rely on the modern security and tools while being kept separate. This may be useful for developers who need to preserve a possibly insecure system without large changes needing to be made.

Jails are often used in place of a virtual machine, for either FreeBSD, or virtualization of another operating system such as Linux. Some developers looking to port tools and drivers to FreeBSD may find this useful.

Creating a Jail

Note: while the process creating a jail is quite simple, actual application and configuration requires a decent understanding of the FreeBSD operating system. This guide is aimed at people who are already familiar with the basics of the FreeBSD operating system.

Identify and create a directory for the jail. This is where the jail will physically reside within the file system of the jail’s host. A good choice can be /usr/jail/jailname, where jailname is the hostname identifying the jail. Usually, /usr/ has enough space for the jail file system, which for “complete” jails is, essentially, a replication of every file present in a default installation of the FreeBSD base system. In these following examples the directory will be /usr/jail/myjail.

The bsdinstall(8) tool can be used to fetch and install the binaries needed for a jail. Distributions will be installed into the destination directory along with some basic configuration of the jail:

# cd /usr

# mkdir myjail

# bsdinstall jail /usr/jail/myjail

bsdinstall will then start the FreeBSD installation process using the installer.

Once a jail is installed, it can be started by using the jail(8) utility. The 4 elements listed earlier in the guide (directory subtree, hostname, IP address, and command) will serve as mandatory arguments for the utility, but other arguments may be specified too. The command argument depends on the type of the jail employed. For example, if a system requires the startup sequence, such as in the case of a virtual machine, specifying /etc/rc.conf under the command parameter will be ideal.

The FreeBSD rc mechanism provides an easy way to start jails on boot.

Configure specific jail parameters in jail.conf:

myjail { 
    host.hostname = myjail;                        # Set the hostname
    ip4.addr = 192.168.0.10;                       # Set an IP address of the jail 
    path = "/usr/jail/myjail";                     # Path to the jail 
    devfs_ruleset = "5";                           # devfs ruleset 
    mount.devfs;                                   # Mount devfs inside the jail 
    exec.start = "/bin/sh /etc/rc";                # Start command 
    exec.stop = "/bin/sh /etc/rc.shutdown";        # Stop command 
}

A common configuration can also be used. This configuration will be shared by all jails that are not specifically set up like in the previous example:

host.hostname = "$name";                           # Set the hostname using the $name variable
ip4 = inherit;                                     # Inherit IP address from the host
path = "~/jail.$name";                             # Path to the jail
devfs_ruleset = $name_ruleset";                    # devfs ruleset
mount.devfs;                                       # Mount devfs inside the jail
exec.start = "/bin/sh /etc/rc";                    # Start command 
exec.stop = "/bin/sh /etc/rc.shutdown";            # Stop command

service(8) can be used to start or stop a jail by hand if an entry for it exists in jail.conf:

# service jail start myjail # service jail stop myjail

More information about this can be found in the jail(8) manual page, including other arguments that can be set for the jail.

Further Configuration

Fine tuning of a jail’s configuration is mostly done by setting sysctl(8) variables. Here is a list of the main jail-related sysctls, complete with their default value. Please refer to the jail(8) and sysctl(8) manual pages for more information on each variable.

security.jail.set_hostname_allowed: 1
security.jail.socket_unixiproute_only: 1
security.jail.sysvipc_allowed: 0
security.jail.enforce_statfs: 2
security.jail.allow_raw_sockets: 0
security.jail.chflags_allowed: 0
security.jail.jailed: 0

These variables will need to be run by the host system system administrator and amend some limitations by default in the jail.

FreeBSD also contains tools for viewing information on active jails and executing commands within the jail itself. The jls(8) command can be used to list all active jails along with their identifier, hostname, path, and IP address. The jexec(8) command can attach to an active jail from the host system in order to run a command or perform administrative tasks. For example jexec(8) can be used to start a shell in an active jail with:

# jexec 1 sh

Updating/Removing a Jail

Jails should be kept as up to date from the host operating system as possible. To update the jail to the latest patch release, execute the following commands on the host:

# freebsd-update -b /usr/jail/myjail fetch # freebsd-update -b /usr/jail/myjail install

To upgrade the jail to a new major or minor version, first upgrade the host system as described in “Performing Major and Minor Version Upgrades”. Once the host has been upgraded and rebooted, the jail can then be upgraded. For example to upgrade from 12.3-RELEASE to 13.0-RELEASE, on the host run:

# freebsd-update -b /usr/jail/myjail --currently-running 12.3-RELEASE -r 13.0-RELEASE upgrade # freebsd-update -b /usr/jail/myjail install # service jail restart myjail # freebsd-update -b /usr/jail/myjail install

Then, if it was a major version upgrade, reinstall all installed packages and restart the jail again. This is required because the ABI version changes when upgrading between major versions of FreeBSD. From the host:

# pkg -j myjail upgrade -f # service jail restart myjail

In order to remove a jail, simply remove the directory after making sure that the service has stopped:

# service jail stop myjail
# rm -rf myjail

The post An Introduction to FreeBSD Jails first appeared on FreeBSD Foundation.

Bulk Port Management With Poudriere

Anne Dickison — Mon, 15 Aug 2022 18:14:49 +0000

Updated: September 10, 2021

Step 1: Using the Ports Collection to Install Poudriere:

All commands in this section should be run as root, using the su(1) command will work. You’ll need to start by installing git:

# pkg install git

Then, use git to clone the ports collection into /usr/ports:

# git clone https://git.freebsd.org/ports.git /usr/ports

Next, build and install Poudriere from the ports collection using:

# cd /usr/ports/ports-mgmt/poudriere

# make install clean

Prompts will appear throughout the installation process, stick with the default settings and install the port.

Step 2: Configuring Poudriere

Poudriere is an extremely powerful tool designed for package production, but can also be used to bulk manage ports. In order to do so, a few small tweaks will need to be made to the configuration before moving forward.
First, copy and move the configuration file to the correct location with:

# cd /usr/local/etc

# cp poudriere.conf.sample poudriere.conf

Then use the ee(1) text editor to edit the copied configuration file:

# ee poudriere.conf

Arrow keys can be used to navigate down to the line:

FREEBSD_HOST=_PROTO_://_CHANGE_THIS_

Edit the above line, so it instead looks like this: (backspace to delete text)

FREEBSD_HOST=ftp://ftp.freebsd.org

Type ESCAPE and then ENTER twice to exit and save changes to the configuration file.

Step 3: Set Up a Poudriere Jail

Before continuing, Poudriere will need to fetch and extract its own version of the FreeBSD ports collection. In order to do this, run:

# rehash

# poudriere ports -c

A FreeBSD jail will need to be set up for Poudriere to perform bulk functions. This can be done with the commands:

# mkdir /usr/local/poudriere

# poudriere jail -c -j 91x64 -v 12.1-RELEASE -a amd64

In the above command, 91x64 identifies the jail, while 12.1-RELEASE identifies the FreeBSD version to use. These can be tweaked if a different name or FreeBSD version is required. Just remember to also replace them in the rest of this guide.

Step 4: Creating a Bulk List of Ports

Before continuing, run the following:

# cd poudriere.d

# echo WITH_PKGNG=YES >> 91x64-make.conf

The next step will be to create a list of ports for poudriere to compile and maintain, a wide range of ports are available in the FreeBSD ports collection, and poudriere can be used to manage them all. Start with:

# cd /usr/local/etc

# ee poudriere-list

As before, use the ee(1) text editor to edit the file, adding a list of ports for poudriere to manage. Above is an example image including Firefox, the i3 windows manager, irssi, and tmux. Ports can be added to the list by using the port origin (category/name).
Type ESCAPE and then ENTER twice to exit and save changes to the configuration file.

Step 5: Configuring Poudriere Installation Options

This step is optional unless manual configuration is needed.

While poudriere can be used to automate bulk port management, it still allows users to manually configure each port. However, this step can be done before installation instead of having to be present for the entirety of the process. If, for instance, the user wants to edit tmux(1), use the command:

# poudriere options -c sysutils/tmux

Then, using the installation prompts (arrows keys to navigate, space to select) the port can be manually edited. This process can be done for each port that poudriere manages.

Step 6: Using Poudriere to Manage Ports

With configuration complete, installing the entire list of ports can be done with just one command:

# poudriere bulk -j 91x64 -f poudriere-list

Poudriere will take some time to complete the bulk process, but unlike manually building and installing ports, it can do all the work without needing user inputs. Poudriere also offers a text-based visual display of the installation process. It will allow users to have greater control over their ports without sacrificing automation.
If an update is needed to the port list, poudriere can update the port collection with the commands:

# cd /usr/local/etc

# poudriere bulk -j 91x64 -f poudriere-list

The post Bulk Port Management With Poudriere first appeared on FreeBSD Foundation.

Building a Physical FreeBSD Build Status Dashboard

Anne Dickison — Mon, 15 Aug 2022 15:51:46 +0000

Introduction

FreeBSD now has a number of continuous integration jobs on Jenkins CI to build and test FreeBSD on various architectures, and the newly implemented Tinderbox View presents a high-level, simple dashboard to the real-time FreeBSD CI build status.

This display is so useful that we wanted a physical version in our office to monitor the build status more easily. What started as a side project during my first few weeks of interning at The FreeBSD Foundation, has become a useful LED display of the current FreeBSD CI (continuous integration) build status, and is running 24/7 in the Foundation Kitchener office, proudly running FreeBSD on a BeagleBone Green.

Prerequisites

A working installation of FreeBSD
BeagleBone Green with a 4GB micro-SD card, a serial cable and Internet connection
An addressable LED RGB strip. This project uses an APA102 LED strip from Sparkfun

Steps

Install FreeBSD on the micro-SD card

1. Build or download a FreeBSD image

To get started, you can download an image from the FreeBSD Snapshot site with filename labeled as BeagleBone. In this case, we download:

FreeBSD-12.0-CURRENT-arm-armv6-BEAGLEBONE-20170519-r318502.img.xz

then extract it:

$ unxz FreeBSD-12.0-CURRENT-arm-armv6-BEAGLEBONE-20170519-r318502.img.xz

to get the .img image.

You can always choose to build FreeBSD from source code if you want to experience the latest changes for the support of BeagleBone and are comfortable with the process. Crochet is the tool to use, and you can find a detailed guide on GitHub.

2. Install the image

The dd(1) utility is used for raw data copying such as, initializing a disk from a raw image.

dd requires specifying if (input file), of (output file) and bs (copy block size). These arguments should be changed to match the actual file and device name.

$ dd if=FreeBSD-BeagleBone.img of=/dev/da0 bs=8m

Specifying a block size is not necessary, but the default setting will result in very slow operation.

If you are not sure of which device it is, simply run:

$ tail /var/log/messages

right after inserting the micro-SD, or:

$ sudo camcontrol devlist

to see the corresponding device name.

After the operation finishes, you can insert the micro-SD card into the BeagleBone.

Boot the BeagleBone Green

1. Connect the serial cable

A serial cable might not be necessary as you can wait until it boots and try to ssh to it (the system configuration might prevent you from logging in as root with ssh though). However, since BeagleBone Green doesn’t have an HDMI output, you can see what is going on through the whole booting process with a serial cable, making it much easier to diagnose if something goes wrong.

The serial console of BeagleBone Green is exposed on a 6-pin header.

The built-in cu(1) utility can be used for serial communications. cu can only access the /var/spool/lock directory via user uucp and group dialer. Use the dialer group to control who has access to the modem or remote systems by adding user accounts to dialer using pw(8):

$ sudo pw groupmod dialer -m guangyuan # Use your own username

Then log out and log in again to make the above change live.

Connect the USB to TTL cable to BeagleBone and computer, then run the cu utility and specify the line speed of 115200 baud.

$ cu -s 115200 -l /dev/cuaU0 # Or appropriate device

You won’t see any output yet.

Note: Using sudo to use cu is not a good practice, instead you should add the user to the dialer group as above stated, or grant everyone’s access as an alternative by running:

$ chmod 4511 /usr/bin/cu

For more info about serial communications, see FreeBSD Serial Communications.

2. Boot up and log in

The BeagleBone Black can boot from either the onboard eMMC or a micro-SD card. By default it boots from eMMC. To boot from micro-SD, first hold down the boot switch, then apply power. Don’t release the button until you see it starts booting FreeBSD (or count to 5).

(image from http://wiki.seeed.cc/BeagleBone_Green/)

The boot switch is just above the micro-SD slot.

After booting, log in as root (the default password is “root” as well).

Tip: Making a BeagleBone Black Always Boot From the Micro-SD
The AM335x chip on board actually boots from the first partition that has the active flag set. After using the “holding the boot button” method described above to boot FreeBSD and log in as root, you will be able to turn off the bootable flag of the onboard eMMC to make it always boot from the micro-SD:

 $ gpart unset -a active -i 1 mmcsd1

To restore this change and make the eMMC available again do:

 $ gpart set -a active -i 1 mmcsd1

Alternatively, you can copy the FreeBSD image to eMMC so no pressing the button is needed.

3. Sync system clock

The system may refuse to proceed on some commands if the system clock is wrong.

In FreeBSD, it is recommended to use both ntpdate and ntpd. ntpdate will set the clock when you first boot so it’s close enough that ntpd will work with it. Add the following to /etc/rc.conf:

 ntpd_enable="YES"
 ntpdate_enable="YES"

Then read through /etc/ntp.conf. It’s pretty well documented so it should be obvious what to set.

4. Enable root login via ssh

Open /etc/ssh/sshd_config and change this line:

 #PermitRootLogin no

to:

 PermitRootLogin yes

then, restart the ssh daemon:

 $ /etc/rc.d/sshd restart

and you will be able to login as root via ssh.

Test the GPIO on board

Let us start from mastering the control of an external LED.

1. GPIO wiring

First let’s take a look at Beaglebone Green’s pin map:

(image from http://wiki.seeed.cc/BeagleBone_Green/)

Now we connect a LED and a 200Ω resistor using jumper wires.

(image from https://learn.adafruit.com/blinking-an-led-with-beaglebone-black/wiring)

The top two connections on the BeagleBone expansion header are both GND. The other lead is connected to a pin of your choice.

2. Send test signals

No programming is required at this moment, as FreeBSD provides us with the gpioctl(8) utility which could be used to list available pins and manage GPIO pins from userland.

Let’s list all the available pins defined by device /dev/gpioc0:

 $ gpioctl -f /dev/gpioc0 -l

By default, all the IO pins are set to be inputs. This does not work for our LED. Instead, we need the pin it is connected to be an output, so we configure that:

 $ gpioctl -f /dev/gpioc0 -c 3 OUT # Assuming pin 3 is the one used

The pin should be output mode now, but the LED should still be off. To turn it on, type:

 $ gpioctl -f /dev/gpioc0 3 1 # Assuming pin 3 is the one used

Now we have set the logical value of pin 3 to be 1, and the LED is on! To turn it off again, type:

 $ gpioctl -f /dev/gpioc0 3 0 # Assuming pin 3 is the one used

You can try blinking the LED by writing a bash script with a simple loop.

SPI bit banging

Awesome! GPIO is working well with BeagleBone, it’s time to start using the addressible LED strip.

The LED RGB strip we used is packed with 60 APA102s and can be controlled with a standard SPI interface. However, at this moment, FreeBSD has no userland support for SPI devices. We used Bit banging to simulate the SPI Protocol as a workaround.

1. Wire LED strip to the BeagleBone

(image from https://www.sparkfun.com/products/14015)

Using the pin map, we connected:
VCC -> SYS_5V
CI -> GPIO of your choice
DI -> GPIO of your choice
GND -> DGND

2. Install Python development environment

We used Python and the fbsd_gpio python bindings for the code. Install Python and pip first, and then cffi and fbsd_gpio libraries via PyPI.

 $ pkg install python py27-pip
 $ pip install --user cffi fbsd_gpio

Note: You may encounter an error when using `pip` which will give an error like:

unable to execute '/nxb-bin/usr/bin/cc': No such file or directory

This is because FreeBSD uses some cross-compile tools on some embedded platforms (mips, arm, aarch64, etc.) which aren’t used in this setup and will cause build errors. The bug has not been fixed yet (Bug 208282), but in the meantime, we could just change all references in /usr/local/lib/python2.7/_sysconfigdata.py as a workaround:

 $ sed -i '' 's/\/nxb-bin\/usr\/bin\/cc/\/usr\/bin\/cc/g' /usr/local/lib/python2.7/_sysconfigdata.py

3. Write SPI bit banging functions

There is a SPI bit banging abstraction in the fbsd_gpio package used below but has not been documented yet. You can use that abstraction and skip this step, or you can still choose to follow it as a good learning practice.

Import the library and create a controller:

 from fbsd_gpio import GpioController
 gpioc = GpioController(0) # Using gpio controller unit 0 (/dev/gpioc0)

Set which pins we are using:

 SCLK = 2 # CI (Blue)
 MOSI = 3 # DI (Green)

Note:
SCLK: Serial Clock (output from master)
MOSI: Master Output Slave Input (data output from master), or DI from LED

Provide SPI init and write functions (it’s better to use bitwise operators when working with bits):

 def spi_init():
     gpioc.pin_output(SCLK)
     gpioc.pin_output(MOSI)
     gpioc.pin_set(SCLK, 0)
     gpioc.pin_set(MOSI, 0)


 def spi_write_byte(b):
     for i in xrange(7, -1, -1):
         gpioc.pin_set(SCLK, 0)
         gpioc.pin_set(MOSI, (b >> i) & 1)
         gpioc.pin_set(SCLK, 1)


 def spi_write(buf):
     for i in buf:
         spi_write_byte(i)

A complete description of fbsd_gpio can be found in the fbsd_gpio documentation on PyPI.

4. Work with APA102 LEDs

Once we set up the SPI functions, we were ready to send SPI data, but first we needed to figure out what to send in order to light up the LEDs we want. Follow the APA102 Manual to find out the data format:

(image from https://cdn-shop.adafruit.com/datasheets/APA102.pdf)

Each update consists of a start frame of 32 zeroes, 32 bits for every LED, and an end frame of 32 ones. So our send function will most likely to work as follows:

 # Start Frame
 spi_write([0b00000000, 0b00000000, 0b00000000, 0b00000000])

 # LED Frames
 spi_write([0b11111111, 0b00000001, 0b00000000, 0b00000000]) # First LED, brightness full, blue
 ...

 # End Frame
 spi_write([0b11111111, 0b11111111, 0b11111111, 0b11111111])

Read this article if you want to Understand the APA102 “Superled” better.

Display the status

1. Get data from Jenkins

Many objects of Jenkins provide remote access APIs. We used the provided Python one to get status of all jobs:

 import ast
 import urllib
 JENKINS_URL = "https://ci.freebsd.org/api/python?tree=jobs[name,color]"
 data = ast.literal_eval(urllib.urlopen(JENKINS_URL).read())["jobs"]

This is how the data will look like:

 {
   "_class" : "hudson.model.Hudson",
   "jobs" : [
     {
       "_class" : "hudson.model.FreeStyleProject",
       "name" : "FreeBSD-doc-head",
       "color" : "blue"
     },
     {
       "_class" : "hudson.model.FreeStyleProject",
       "name" : "FreeBSD-doc-head-igor",
       "color" : "blue_anime"
     },
     ...
   ]
 }

And the latest status could be extracted from color attribute in data["jobs"] and stored in a dictionary called status.

The Jenkins API manual can be found in the Jenkins CI API reference.

2. Light up the LEDs

Recalling the APA102 data format, we wrote some predefined data frames:

 # Variables
 BRT = 224 + 16 # Brightness, 0~31 decimal

 # Predefined data frames
 START_FRAME = [0, 0, 0, 0]
 END_FRAME = [255, 255, 255, 255]
 BLUE_LED_FRAME = [BRT, 1, 0, 0]
 GREEN_LED_FRAME = [BRT, 0, 1, 0]
 RED_LED_FRAME = [BRT, 0, 0, 1]
 YELLOW_LED_FRAME = [BRT, 0, 1, 1]
 OFF_LED_FRAME = [224, 0, 0, 0]

and some send functions:

def led_send_start():  
spi_write(START_FRAME)


def led_send_end():  
spi_write(END_FRAME)  


def led_send(status):  
    if status in ["blue", "blue_anime"]:  
        spi_write(GREEN_LED_FRAME)  
    elif status in ["red", "red_anime"]:  
        spi_write(RED_LED_FRAME)  
    elif status in ["dne"]:  
        spi_write(OFF_LED_FRAME)  
    else:  
        spi_write(YELLOW_LED_FRAME)  


def led_send_all(jobs):  
    led_send_start()  
    for job in jobs:  
        led_send(job["status"])  
        led_send_end()

so that once we updated the status dictionary, we were able to use led_send(status) to update the display:

 if __name__ == "__main__":
     spi_init()
     while True:
         status = ... # Fetch the data
         led_send_all(status) # Update
         time.sleep(10) # or any other interval

3. Let them blink!

Now the display works really well with the static states of the job. However, we noticed that the blue_anime and red_anime colours in Jenkins, which indicate a project is in the process of building (and should be blinking), were treated as static status in the code.

How can we make the LEDs blink while keeping their current status? We added a blink_flag boolean inside the loop, reversed it each time, and decided if we should turn the lights off based on that.

Add the flag to the LED updating loop:

 blink_flag = False
 while True:
     status = ... # Fetch the data
     blink_flag = not blink_flag
     led_send_all(status, blink_flag) # Update
     time.sleep(10) # or any other interval

and reflect changes in the send function:

 def led_send_all(jobs, blink_flag):
     led_send_start()
     for job in jobs:
         if "anime" in job["status"]:
             if blink_flag:
                 led_send(job["status"])
             else:
                 led_send("dne")
          else:
              led_send(job["status"])
     led_send_end()

We considered splitting the data fetching and the LED updating process, since blinking requires updating the LEDs every 0.5s, but fetching data should be every 20s or even longer. This could be achieved by simply adding a nested loop (for example, 40 led updates, 1 data updates, loop), but I chose to use threading so both jobs will not affect each other if one gets stuck.

Move the LED updating process into a controller class and run it separately:

import threading
class Led_controller(threading.Thread):
    def run(self):
        blink_flag = False
        while True:
            blink_flag = not blink_flag
            led_send_all(status, blink_flag)
            time.sleep(0.5)

if __name__ == "__main__":
    spi_init()
    led_controller = Led_controller()
    led_controller.start()

while True:
    status = ... # Fetch the data
    time.sleep(10) # or any other interval

And the LEDs should be able to blink at an interval of 0.5s.

Add some final touches

We cut the strip to parts and stuck them inside a picture frame.

Looking good!

Thanks

I would like to thank my supervisor Ed Maste for his guidance and support on my work. I would also like to thank Siva Mahadevan, my colleague and friend, for the help and useful suggestions.

– Contributed by Guangyuan (Charlie) Yang

The post Building a Physical FreeBSD Build Status Dashboard first appeared on FreeBSD Foundation.

3 | FreeBSD Foundation

How to use VS Code on FreeBSD

Requirements:

Installation and Configuration:

Using VS Code:

Troubleshooting VS Code:

An Introduction to Packet Filter (PF)

1 . Enabling PF

2. Using pfctl

3. Creating a Base PF Ruleset

4. Testing Your Base Ruleset

5. Example Rulesets and Their Application

5.1 Blocking Spoofed Packets

5.2 Protecting SSH Ports

5.3 Handling Non-Routable Addresses

6. Viewing PF Logs

An Introduction to ZFS

Getting Started

Identify Hardware

Creating a Single Disk Pool

RAID-Z

Recovering RAID-Z

Data Verification

ZFS Administration

Further Resources

Video Playback on FreeBSD – Quick Guide

System Requirements:

Installing Xorg

XVideo Support

The xine Video Player

An Introduction to FreeBSD Jails

What are Jails?

Examples of Jails

Creating a Jail

Further Configuration

Updating/Removing a Jail

Bulk Port Management With Poudriere

Step 1: Using the Ports Collection to Install Poudriere:

Step 2: Configuring Poudriere

Step 3: Set Up a Poudriere Jail

Step 4: Creating a Bulk List of Ports

Step 5: Configuring Poudriere Installation Options

Step 6: Using Poudriere to Manage Ports

Building a Physical FreeBSD Build Status Dashboard

Introduction

Prerequisites

Steps

Install FreeBSD on the micro-SD card

1. Build or download a FreeBSD image

2. Install the image

Boot the BeagleBone Green

1. Connect the serial cable

2. Boot up and log in

3. Sync system clock

4. Enable root login via ssh

Test the GPIO on board

1. GPIO wiring

2. Send test signals

SPI bit banging

1. Wire LED strip to the BeagleBone

2. Install Python development environment

3. Write SPI bit banging functions

4. Work with APA102 LEDs

Display the status

1. Get data from Jenkins

2. Light up the LEDs

3. Let them blink!

Add some final touches

Further reading

Thanks