Christos Margiolis: bsd

PostgreSQL 15 and pgAdmin4 on FreeBSD

Thu, 07 Sep 2023 00:00:00 +1200

Tested on FreeBSD 13.2. This article is also mirrored on the FreeBSD Wiki.

PostgreSQL

Install PostgreSQL:

# pkg install postgresql15-server postgresql15-client

Enable the PostgreSQL service:

# sysrc postgresql_enable="YES"

Initialize PostgreSQL and start the service:

# /usr/local/etc/rc.d/postgresql initdb
# service postgresql start

Make sure the service is running properly on IPv4 and IPv6 port 5432:

$ sockstat -46 | grep 5432

Set a password for the default postgres user:

# passwd postgres

Create an owner user for your database:

# su - postgres
$ createuser admin
$ createdb foo_db -O admin

Inside the psql prompt, set an encrypted password for admin and grant exclusive access to foo_db to the admin user:

$ psql foo_db
foo_db=# alter role admin with encrypted password 'yourpassword';
foo_db=# grant all privileges on database foo_db to admin;
foo_db=# exit
$ exit

Make PostgreSQL listen to all addresses, instead of just localhost.

# vi /var/db/postgres/data15/postgresql.conf

Uncomment the listen_addresses line and set it to:

listen_addresses = '*'

Change the security settings:

# vi /var/db/postgres/data15/pg_hba.conf

Go to the bottom of the file and set trust to md5 for all existing entries:

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     md5
# IPv4 local connections:
host    all             all             127.0.0.1/32            md5
# IPv6 local connections:
host    all             all             ::1/128                 md5
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     md5
host    replication     all             127.0.0.1/32            md5
host    replication     all             ::1/128                 md5

Also, allow remote IPv4 and IPv6 connections to our new database as admin only:

# Allow remote connections to foo_db as admin
host    foo_db          admin           0.0.0.0/0               md5
host    foo_db          admin           ::/0                    md5

Restart the service:

# serivce postgresql restart

pgAdmin4

Install the needed packages:

# pkg install python py39-pip py39-virtualenv py39-sqlite3 ca_root_nss openjpeg rust

Upgrade pip to the latest version:

$ pip install --upgrade pip

Initialize the virtualenv for pgAdmin4 in your home directory:

$ cd
$ virtualenv pgadmin4

Enter the virtualenv and install pgAdmin4. This will take a while:

$ . pgadmin4/bin/activate
(pgadmin4) $ pip install pgadmin4

Create a local config file:

(pgadmin4) # mkdir -p /var/lib/pgadmin /var/log/pgadmin
(pgadmin4) $ cp pgadmin4/lib/python3.9/site-packages/pgadmin4/config.py pgadmin4/lib/python3.9/site-packages/pgadmin4/config_local.py
(pgadmin4) $ vi pgadmin4/lib/python3.9/site-packages/pgadmin4/config_local.py

Inside config_local.py, edit the following values:

DEFAULT_SERVER = '0.0.0.0'
DEFAULT_SERVER_PORT = 5050

Start pgAdmin4 (always inside the virtualenv) and set up your account:

(pgadmin4) # pgadmin4
Email address: you@mail.com
Password: yourpassword
Retype password: yourpassword

Open a web browser and enter pgAdmin4 (replace the IP with the appropriate one) and log in with the email and password you just entered in the pgadmin4 prompt:

http://192.168.1.11:5050

Inside the web interface, go to File -> Preferences -> Binary Paths and under the PostgreSQL Binary Path section, check PostgreSQL 15 and set the binary path to /usr/local/bin/. Then click Save.

From now on, you can run pgadmin4 in the background like so:

(pgadmin4) # pgadmin4 &

Upgrading pgAdmin4

To upgrade pgAdmin4, you only have to delete and reinstall the virtualenv:

$ cd
$ rm -rf pgadmin4
$ virtualenv pgadmin4
$ . pgadmin4/bin/activate
(pgadmin4) $ pip install --upgrade pgadmin4

You also have to re-create config_local.py and set DEFAULT_SERVER (see above).

Inline function tracing with the kinst DTrace provider

Tue, 18 Jul 2023 00:00:00 +1200

Quick background

DTrace is a framework that gives administrators and kernel developers the ability to observe kernel behavior in real time. DTrace has modules called “providers”, that perform a particular instrumentation in the kernel (and sometimes userland) using “probes”.

kinst is a new low-level DTrace provider co-authored by Christos Margiolis and Mark Johnston for the FreeBSD operating system, which allows the user to trace arbitrary instructions in kernel functions. It is part of the base system as of FreeBSD 14.0.

kinst probes take the form of kinst::<function>:<instruction>, where <function> is the kernel function to be traced, and <instruction> is the offset to the instruction, relative to the beginning of the function, and can be obtained from the function’s disassembly. If the <instruction> field is left empty, kinst will trace all instructions in that function. Unlike FBT, kinst can also trace the entry and return points of inline functions (see Inline function tracing).

The origin of the name is inspired from an early paper written by A. Tamches and B. Miller discussing a tracing tool they developed called “KernInst”.

Usage

Find the offset corresponding to the third instruction in vm_fault() and trace it, printing the contents of the RSI register:

# kgdb
(kgdb) disas /r vm_fault
Dump of assembler code for function vm_fault:
   0xffffffff80f4e470 <+0>:     55      push   %rbp
   0xffffffff80f4e471 <+1>:     48 89 e5        mov    %rsp,%rbp
   0xffffffff80f4e474 <+4>:     41 57   push   %r15
...

# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}'
  2  81500                       vm_fault:4 0x827c56000
  2  81500                       vm_fault:4 0x827878000
  2  81500                       vm_fault:4 0x1fab9bef0000
  2  81500                       vm_fault:4 0xe16cf749000
  0  81500                       vm_fault:4 0x13587c366000
  ^C

Trace the return point of critical_enter(), which is an inline function:

# dtrace -n 'kinst::critical_enter:return'
dtrace: description 'kinst::critical_enter:return' matched 130 probes
CPU     ID                    FUNCTION:NAME
  1  71024                spinlock_enter:53
  0  71024                spinlock_enter:53
  1  70992                uma_zalloc_arg:49
  1  70925    malloc_type_zone_allocated:21
  1  70994                uma_zfree_arg:365
  1  70924             malloc_type_freed:21
  1  71024                spinlock_enter:53
  0  71024                spinlock_enter:53
  0  70947         _epoch_enter_preempt:122
  0  70949           _epoch_exit_preempt:28
  ^C

Inline function tracing

How it works

To trace inline functions, libdtrace makes use of the DWARF Debugging Standard, to detect if the function specified is an inline call. If it is, D syntax is transformed to create kinst probes for each of the inline copies found. All work is done in libdtrace, instead of kinst(4). This feature has been added to FreeBSD with this patch.

Contrary to how kinst expects a <function>:<instruction> tuple to create probes, for inline functions, <instruction> is replaced by entry and return.

Syntactic transformations

Suppose the user wants to trace a probe of the form:

kinst::<func>:<entry|return>
/<pred>/
{
	<acts>
}

libdtrace sees that we have specified entry or return, instead of an offset, which is what a regular kinst probe would look like, so it loops through all loaded kernel modules and parses their DWARF and ELF info to see if this function is an inline — if not, the probe is converted to an FBT one, so that we don’t duplicate FBT’s functionality in kinst:

# dtrace -dn 'kinst::malloc:entry {exit(0);}'
fbt::malloc:entry
{
        exit(0x0);
}

dtrace: description 'kinst::malloc:entry ' matched 1 probe
CPU     ID                    FUNCTION:NAME
  2  31144                     malloc:entry

If the function however is an inline, libdtrace will find all calls refering to this function and create new probes for each one of the inline copies found.

# dtrace -dn 'kinst::cam_iosched_has_more_trim:entry { printf("\t%d\t%s", pid, execname); }'
kinst::cam_iosched_get_trim:13,
kinst::cam_iosched_next_bio:13,
kinst::cam_iosched_schedule:40
{
	printf("\t%d\t%s", pid, execname);
}

dtrace: description 'kinst::cam_iosched_has_more_trim:entry ' matched 4 probes
CPU     ID                    FUNCTION:NAME
  0  81502          cam_iosched_schedule:40     2       clock
  0  81501          cam_iosched_next_bio:13     2       clock
  2  81502          cam_iosched_schedule:40     2       clock
  1  81502          cam_iosched_next_bio:13     0	kernel
  1  81503          cam_iosched_schedule:40     0	kernel
^C

There can also be both inline and non-inline definitions of the same function. In this case, kinst creates an additional FBT probe for the non-inline definition.

The -d flag used in these examples to dump the D script after libdtrace has applied syntactic transformations, has been added to DTrace in commit 1e136a9cbd3a.

Heuristic for calculating the `entry` and `return` offsets

libdtrace reuses parts of the mechanism implemented in my inlinecall(1) program, which finds and prints all call sites of a given inline function:

$ ./inlinecall vm_page_mvqueue /usr/lib/debug/boot/kernel/kernel.debug
/usr/src/sys/vm/vm_page.c:4142
        [0xffffffff80f91541 - 0xffffffff80f91599]       /usr/src/sys/vm/vm_page.c:4195  vm_page_readahead_finish()
        [0xffffffff80f915f5 - 0xffffffff80f91603]       /usr/src/sys/vm/vm_page.c:4195  vm_page_readahead_finish()
        [0xffffffff80f9163d - 0xffffffff80f916c2]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916cd - 0xffffffff80f916e5]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916fe - 0xffffffff80f91747]       /usr/src/sys/vm/vm_page.c:4195  vm_page_deactivate()
        [0xffffffff80f91750 - 0xffffffff80f91768]       /usr/src/sys/vm/vm_page.c:4195  vm_page_deactivate()
        [0xffffffff80f94a59 - 0xffffffff80f94aa9]       /usr/src/sys/vm/vm_page.c:4195  vm_page_reclaim_contig_domain()
        [0xffffffff80f94de4 - 0xffffffff80f94df9]       /usr/src/sys/vm/vm_page.c:4195  vm_page_reclaim_contig_domain()
        [0xffffffff80f9661e - 0xffffffff80f96667]       /usr/src/sys/vm/vm_page.c:4202  vm_page_deactivate_noreuse()
        [0xffffffff80f96670 - 0xffffffff80f96688]       /usr/src/sys/vm/vm_page.c:4202  vm_page_deactivate_noreuse()
        [0xffffffff80f9669e - 0xffffffff80f966ea]       /usr/src/sys/vm/vm_page.c:4212  vm_page_launder()
        [0xffffffff80f966f3 - 0xffffffff80f9670b]       /usr/src/sys/vm/vm_page.c:4212  vm_page_launder()
        [0xffffffff80f96d4c - 0xffffffff80f96dac]       /usr/src/sys/vm/vm_page.c:4212  vm_page_advise()
        [0xffffffff80f96dac - 0xffffffff80f96e07]       /usr/src/sys/vm/vm_page.c:4202  vm_page_advise()

Most of the entries above appear twice but with different boundaries:

        [0xffffffff80f9163d - 0xffffffff80f916c2]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()
        [0xffffffff80f916cd - 0xffffffff80f916e5]       /usr/src/sys/vm/vm_page.c:4184  vm_page_activate()

This means that the inline copy’s boundaries are split into more than one parts, which can be caused by having early returns inside the inline function. By using this assumption, we can deduce that the entry point of the function is 0xffffffff80f9163d, and each of the upper boundaries are the return points (i.e 0xffffffff80f916c2 and 0xffffffff80f916e5), so we end up with one entry and two return trace points.

However, this is not exactly true, because the final return address given by DWARF corresponds to the instruction after the actual return instruction. We can verify this in GDB using the two return addresses from the example above:

# kgdb
(kgdb) disas vm_page_activate
...
   0xffffffff80f916c0 <+144>:   jmp    0xffffffff80f91673 <vm_page_activate+67>
   0xffffffff80f916c2 <+146>:   add    $0x8,%rsp			<-- first address given by DWARF
...
   0xffffffff80f916e0 <+176>:   call   0xffffffff80bed360 <panic>	<-- last instruction
									<-- second address should be here

It turns out that 0xffffffff80f916e5 is, in fact, outside vm_page_activate() altogether!

(kgdb) x/i 0xffffffff80f916e5
   0xffffffff80f916e5:  data16 cs nopw 0x0(%rax,%rax,1)

After running a couple of tests, I came to the conclusion that there are two possible cases with return addresses:

If the inline copy’s DIE has DW_AT_lowpc and DW_AT_highpc set, the return address is always outside the inline function’s boundaries.
If the inline copy’s DIE has DW_AT_ranges set, only the last return address is outside the inline function’s boundaries.
Combining the two bullets above, if the return address of the inline function is the same as the upper boundary of the caller function, it’s outside both the inline copy’s and the caller function’s boundaries.

In order to fix this, we have to go one instruction back whenever we come across one of those 3 cases.

Finally the entry offset is calculated as:

inline_bound_lo - caller_bound_lo

And the return one, including the modifications (if any) discussed above, as:

inline_bound_hi - caller_bound_lo

These offsets are then used to create regular kinst probes of the form kinst::<func>:<instruction>, which is what kinst actually expects:

# dtrace -dn 'kinst::vm_page_mvqueue:entry,kinst::vm_page_mvqueue:return'
dtrace: description 'kinst::vm_page_mvqueue:entry,kinst::vm_page_mvqueue:return' matched 22 probes
kinst::vm_page_readahead_finish:33,
kinst::vm_page_readahead_finish:121,
kinst::vm_page_activate:13,
kinst::vm_page_deactivate:14,
kinst::vm_page_reclaim_contig_domain:1961,
kinst::vm_page_deactivate_noreuse:14,
kinst::vm_page_launder:14,
kinst::vm_page_advise:236,
kinst::vm_page_advise:332,
kinst::vm_page_readahead_finish:220,
kinst::vm_page_activate:146,
kinst::vm_page_activate:176,
kinst::vm_page_deactivate:87,
kinst::vm_page_deactivate:115,
kinst::vm_page_reclaim_contig_domain:2041,
kinst::vm_page_reclaim_contig_domain:2884,
kinst::vm_page_deactivate_noreuse:87,
kinst::vm_page_deactivate_noreuse:115,
kinst::vm_page_launder:90,
kinst::vm_page_launder:118,
kinst::vm_page_advise:330,
kinst::vm_page_advise:421
{
}

CPU     ID                    FUNCTION:NAME
  3  95381              vm_page_activate:13 
  3  95389             vm_page_activate:146 
  2  95381              vm_page_activate:13 
  2  95389             vm_page_activate:146 
  1  95387               vm_page_advise:332 
  1  95400               vm_page_advise:421 
  1  95387               vm_page_advise:332 
  1  95400               vm_page_advise:421 
  1  95387               vm_page_advise:332 
^C

Making a character device kernel module on FreeBSD

Sun, 10 Jul 2022 00:00:00 +1200

This article assumes advanced knowledge of C and a basic understanding of the FreeBSD kernel and programming environment. It is also meant to serve as a template/reference and not a complete implementation.

Sample code can be found here.

Also mirrored on the FreeBSD Wiki.

Implementing the device

malloc declaration

Kernel modules have their own malloc types, which are defined as follows:

MALLOC_DECLARE(M_MYDEV);
MALLOC_DEFINE(M_MYDEV, "mydev", "device description");

Then, you can use malloc(9) and free(9) as:

p = malloc(sizeof(foo), M_MYDEV, M_WAITOK | M_ZERO);
free(p, M_MYDEV);

`cdevsw` structure

The device’s properties and methods are stored in a cdevsw (Character Device Switch) structure, defined in sys/conf.h. The fields we care about most of the time are the following:

struct cdevsw {
	int			d_version;
	u_int			d_flags;
	const char		*d_name;
	d_open_t		*d_open;
	d_fdopen_t		*d_fdopen;
	d_close_t		*d_close;
	d_read_t		*d_read;
	d_write_t		*d_write;
	d_ioctl_t		*d_ioctl;
	d_poll_t		*d_poll;
	d_mmap_t		*d_mmap;
	d_strategy_t		*d_strategy;
	dumper_t		*d_dump;
	d_kqfilter_t		*d_kqfilter;
	d_purge_t		*d_purge;
	d_mmap_single_t		*d_mmap_single;
	...
};

All the *_t pointers are pointers to functions meant to be implemented by the driver. Not all functions have to be implemented however, but we usually do need to implement open(), close(), read(), write() and ioctl().

Declare the functions using some handy typedefs:

static d_open_t		mydev_open;
static d_close_t	mydev_close;
static d_read_t		mydev_read;
static d_write_t	mydev_write;
static d_ioctl_t	mydev_ioctl;

Declare the cdevsw structure:

static struct cdevsw mydev_cdevsw = {
	.d_name     = "mydev",
	.d_version  = D_VERSION,
	.d_flags    = D_TRACKCLOSE,
	.d_open     = mydev_open,
	.d_close    = mydev_close,
	.d_read     = mydev_read,
	.d_write    = mydev_write,
	.d_ioctl    = mydev_ioctl,
};

The D_TRACKCLOSE flag tells the kernel to track when the device closes so that it can close normally in case something goes wrong.

open() and close()

Those two functions are mainly used for resource allocation/deallocation and environment preparation:

static int
mydev_open(struct cdev *dev, int flags, int devtype, struct thread *td)
{
	int error = 0;

	/* do stuff */

	return (error);
}

static int
mydev_close(struct cdev *dev, int flags, int devtype, struct thread *td)
{
	int error = 0;

	/* do stuff */

	return (error);
}

read() and write()

It’s good practice to keep an internal buffer. Below is a very simplified example. The buffer in this example is allocated and deallocated on module load and unload respectively:

#define BUFSIZE (1 << 16)

struct foo {
	char	buf[BUFSIZE + 1];
	size_t	len;
};

static struct foo *foo;

Data to be received or sent back is stored in uio and the copy from user to kernel memory is done through uiomove(9), defined in sys/uio.h:

static int
mydev_read(struct cdev *dev, struct uio *uio, int ioflag)
{
	size_t amnt;
	int v, error = 0;

	/*
	 * Determine how many bytes we have to read. We'll either read the
	 * remaining bytes (uio->uio_resid) or the number of bytes requested by
	 * the caller.
	 */
	v = uio->uio_offset >= foo->len + 1 ? 0 : foo->len + 1 - uio->uio_offset;
	amnt = MIN(uio->uio_resid, v);

	/* Move the bytes from foo->buf to uio. */
	if ((error = uiomove(foo->buf, amnt, uio)) != 0) {
		/* error handling */
	}

	/* do stuff */

	return (error);
}

static int
mydev_write(struct cdev *dev, struct uio *uio, int ioflag)
{
	size_t amnt;
	int error = 0;

	/* Do not allow random access. */
	if (uio->uio_offset != 0 && (uio->uio_offset != foo->len))
		return (EINVAL);

	/* We're not appending, reset length. */
	else if (uio->uio_offset == 0)
		foo->len = 0;

	amnt = MIN(uio->uio_resid, (BUFSIZE - foo->len));
	if ((error = uiomove(foo->buf + uio->uio_offset, amnt, uio)) != 0) {
		/* error handling */
	}

	foo->len = uio->uio_offset;
	foo->buf[foo->len] = '\0';

	/* do stuff */

	return (error);
}

ioctl()

To create an ioctl, you give it a name and #define it using one of the following _IO* macros defined in sys/ioccom.h:

_IO: No parameters.
_IOR: Copy out parameters. Read from device.
_IOW: Copy in paramters. Write to device.
_IOWR: Copy parameters in and out. Write to device and read the modified data back.

Each of those macros* takes 3 arguments:

An arbitrary one-byte “class” identifier.
A unique ID.
The parameter type (can be anything), which is used to calculate the parameter’s size. The macro expands the type to sizeof(type).

* _IO takes only the first 2 arguments (class and ID) since it doesn’t use parameters.

We can now define a few ioctls that take foo_t as a parameter. This is usually done in a separate header file so that programs can use the ioctls:

#include <sys/ioccom.h>

typedef struct {
	int x;
	int y;
} foo_t;

#define MYDEVIOC_READ	_IOR('a', 1, foo_t)
#define MYDEVIOC_WRITE	_IOW('a', 2, foo_t)
#define MYDEVIOC_RDWR	_IOWR('a', 3, foo_t)

mydev_ioctl() is responsible for handling the ioctls we declared:

static int
mydev_ioctl(struct cdev *dev, u_long cmd, caddr_t addr, int flags,
    struct thread *td)
{
	foo_t *fp;
	int error = 0;

	switch (cmd) {
	case MYDEVIOC_READ:
		fp = (foo_t *)addr;
		/* do stuff */
		break;
	case MYDEVIOC_WRITE:
		fp = (foo_t *)addr;
		/* do stuff */
		break;
	case MYDEVIOC_RDWR:
		fp = (foo_t *)addr;
		/* do stuff */
		break;
	default:
		error = ENOTTY;
		break;
	}

	return (error);
}

Creating and destroying the device

Character devices are given a struct cdev handle upon creation, which we usually store as a global variable:

static struct cdev *mydev_cdev;

Devices are created with the make_dev() function, which is defined as:

struct cdev *
make_dev(struct cdevsw *cdevsw, int unit, uid_t uid, gid_t gid, int perms,
    const char *fmt, ...);

sys/conf.h has the definitions of all available flags.

Create the device:

mydev_cdev = make_dev(&mydev_cdevsw, 0, UID_ROOT, GID_WHEEL, 0666, "mydev");

When done, destroy the device:

destroy_dev(mydev_cdev);

Module declaration

Necessary includes:

#include <sys/types.h>
#include <sys/param.h>
#include <sys/conf.h>
#include <sys/systm.h>
#include <sys/kernel.h>
#include <sys/module.h>
#include <sys/malloc.h>
#include <sys/uio.h>

Implement the module’s event handler. This function is called at module load and unload. Since we’re dealing with a character device, it makes sense to create the device upon load and destroy it upon unload:

static int
mydev_modevent(module_t mod, int type, void *arg)
{
	int error = 0;

	switch (type) {
	case MOD_LOAD:
		mydev_cdev = make_dev(&mydev_cdevsw, 0, UID_ROOT, GID_WHEEL,
		    0666, "mydev");
		foo = malloc(sizeof(foo_t), M_MYDEV, M_WAITOK | M_ZERO);
		foo->buf[0] = '\0';
		foo->len = 0;
		break;
	case MOD_UNLOAD: /* FALLTHROUGH */
	case MOD_SHUTDOWN:
		free(foo, M_MYDEV);
		destroy_dev(mydev_cdev);
		break;
	default:
		error = EOPNOTSUPP;
		break;
	}

	return (error);
}

Lastly, declare the module. The first argument is the module’s name, the second one is a pointer to the event handler and the last one is any data we want to supply the event handler with, i.e the arg argument in mydev_modevent():

DEV_MODULE(mydev, mydev_modevent, NULL);

Makefile

KMOD=   mydev
SRCS=   mydev.c

.include <bsd.kmod.mk>

Running the module

$ make
# kldload ./mydev.ko
...
# kldunload ./mydev.ko
$ make clean cleandepend

Testing

To test the module, load it, and create a simple program that opens the device, and makes a few calls to ioctl(2), read(2) and write(2).

Share ZFS datasets with NFS

Sat, 21 May 2022 00:00:00 +1200

Thanks to Mark Johnston <markj@FreeBSD.org> for recommending this configuration. The article is also mirrored on the FreeBSD Wiki.

Host

Add the following lines to /etc/rc.conf:

nfs_server_enable="YES"
mountd_enable="YES"
mountd_flags="-n"
rpc_lockd_enable="YES"
rpc_statd_enable="YES"
rpcbind_enable="YES"

For some reason the NFS server needs to be restarted the first time after boot. A simple way to do this automatically is:

# echo "service nfsd restart" >> /etc/rc.local

Set the sharenfs property to the dataset you want to share. Replace the IPs and pool/dataset* with your desired values. ZFS properties are documented in zfsprops(8).

We’re going to share 2 datasets, one with read-write and one with read-only access:

# chmod -R 777 /pool/dataset_rw
# zfs set sharenfs='-network=192.168.1.0/24,-alldirs' pool/dataset_rw
# zfs set sharenfs='ro=192.168.1.0/24,-alldirs' pool/dataset_ro

Start the NFS server:

# service nfsd start
# service mountd reload

Guest

Acquire the host’s IP address using ifconfig(8) on it first. We’ll assume it’s 192.168.1.5.

Mount the filesystems. /pool/dataset* corresponds to the actual mount point of the dataset in the host:

# mkdir -p /mnt/dataset_rw /mnt/dataset_ro
# mount -t nfs -o rw 192.168.1.5:/pool/dataset_rw /mnt/dataset_rw
# mount -t nfs -o ro 192.168.1.5:/pool/dataset_ro /mnt/dataset_ro

When done, unmount:

# umount /mnt/dataset_rw /mnt/dataset_ro

In case you want the filesystems to be mounted on boot, add the following lines to /etc/fstab:

192.168.1.5:/dataset_rw   /mnt/dataset_rw	nfs     rw      0       0
192.168.1.5:/dataset_ro   /mnt/dataset_ro	nfs     ro      0       0

FreeBSD VNET Jails

Sat, 30 Apr 2022 00:00:00 +1200

This article is also mirrored on the FreeBSD Wiki.

Configuration

The VNET is set up using an if_epair(4) interface bridged with the actual network interface, in my case re0. Just like if_tap(4) interfaces, epairs can be used by one jail at a time, so if you need to run more than one jail at the same time, you have to make more epairs.

If you’re using tap interfaces for bhyve VMs, you can just addm them to the bridge.

Add the following lines to /etc/rc.conf:

if_bridge_load="YES"
if_epair_load="YES"

cloned_interfaces="bridge0"
ifconfig_bridge0="addm re0 up"

Apply changes:

# /etc/netstart

The jail needs to inherit /dev/bpf* from the host in order for networking to work at all. Make a new /etc/devfs.rules ruleset:

[devfsrules_jails=5]
add include $devfsrules_hide_all
add include $devfsrules_unhide_basic
add include $devfsrules_unhide_login
add path 'bpf*' unhide

Restart devfs(8):

# service devfs restart

In /etc/jail.conf, we’ll name the jail foo and give it the other end of the epair we’ll create as its network interface. Its IP address will be acquired using DHCP. The reason I’m manually calling dhclient(8) is because adding ifconfig_epair0b="DHCP" in the jail’s /etc/rc.conf doesn’t work. Options are detailed in jail.conf(5):

path = "/usr/local/jail/$name";
host.hostname="$name";

exec.clean;
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
allow.mount;
allow.raw_sockets = 1;
mount.devfs;
devfs_ruleset="5";
vnet;
sysvmsg=new;
sysvsem=new;
sysvshm=new;

foo {
	vnet.interface = "epair0b";
	exec.start += "dhclient epair0b";
}

Installation

# mkdir -p /usr/local/jail/foo
# bsdinstall jail /usr/local/jail/foo
...
# ifconfig epair0 create
# ifconfig bridge0 addm epair0a
# ifconfig epair0a up
# service jail onestart foo

Test to see if the jail has networking:

# jexec foo ping google.com

On jail shutdown, destroy the epair:

# service jail onestop foo
# ifconfig epair0a destroy

Delete jail

Deleting jails isn’t as straight forward, so I’m leaving this here as well:

# service jail onestop foo
# chflags -R noschg /usr/local/jail/foo
# rm -rf /usr/local/jail/foo

FreeBSD sound mixer improvements

Fri, 25 Feb 2022 00:00:00 +1200

This project was part of Google Summer of Code 2021, but development is still active. The development report can be found on the FreeBSD Wiki. The reason behind this project is that the FreeBSD’s OSS mixer capabilities were really basic and outdated — even un/muting didn’t exist and one had to write custom scripts for such a basic task. Setting default audio devices had to be done by tweaking sysctls and programs needing to use the mixer required DIY implementations as there was no mixer library available. The project was merged to upstream on FreeBSD 14.0.

Kernel patches

Un/muting (commit)

I decided that un/muting is better to be implemented in sound(4) in order to avoid having to write daemons or use files. The way this works is by implementing the SOUND_MIXER_READ_MUTE and SOUND_MIXER_WRITE_MUTE ioctls, which did exist in older OSS implementations, but were considered obselete. One thing to note is that the functionality isn’t the same as their old one. Older OSS versions had those 2 ioctls take/return an integer with a value of 0 or 1, which indicated whether the whole mixer is muted or not. My implementation takes/returns a bitmask that tells which devices are muted. This allows us to mute and unmute only the devices we want, instead of the whole mixer. If you’re familiar with the OSS API, this bitmask works the same way as DEVMASK, RECMASK and RECSRC.

Playback/recording mode information (commit)

Here I implemented a sysctl (dev.pcm.<N>.mode) which gives information about a device’s playback/recording mode. The rationale for this control is to include /dev/sndstat’s mixer information in the output of the new mixer(8). The sysctl can return the following values (NOTE: these values are OR’ed together if more than one mode is supported):

Value	Meaning
0x01	Mixer
0x02	Playback device
0x04	Recording device

Userland

mixer(3) implementation (commit)

mixer(3) provides a simple interface for working with the OSS mixer. The man page explains how the library works, including some examples, so there’s no need to repeat myself. You can see the library in action in the source code for mixer(8).

The basic structure of a program looks like this (link with -lmixer):

#include <err.h>
#include <mixer.h>

int
main(int argc, char *argv[])
{
	struct mixer *m;
	const char *name = "/dev/mixer0";

	if ((m = mixer_open(name)) == NULL)
		err(1, "mixer_open(%s)", name);

	/* do stuff */

	mixer_close(m);
	
	return (0);
}

mixer(8) rewrite (commit)

This implementation is a complete rewrite of the old mixer(8) utility. It now uses mixer(3) as a backend and implements all the new features the library provides. It’s got more command line options and works with a control-oriented interface inspired by OpenBSD’s mixerctl(8). Again, everything is detailed in the man page.

Old mixer(8) output:

$ mixer.old

Mixer vol      is currently set to  85:85
Mixer pcm      is currently set to 100:100
Mixer speaker  is currently set to  74:74
Mixer line     is currently set to   1:1
Mixer mic      is currently set to  67:67
Mixer mix      is currently set to  74:74
Mixer rec      is currently set to  37:37
Mixer igain    is currently set to   0:0
Mixer ogain    is currently set to 100:100
Mixer monitor  is currently set to  67:67
Recording source: mic

New mixer(8) output:

$ mixer

pcm0:mixer: <Realtek ALC662 rev3 (Analog 2.0+HP/2.0)> on hdaa0 kld snd_hda (play/rec) (default)
    vol       = 0.85:0.85     pbk
    pcm       = 1.00:1.00     pbk
    speaker   = 0.74:0.74     rec
    line      = 0.01:0.01     rec
    mic       = 0.67:0.67     rec src
    mix       = 0.74:0.74     rec
    rec       = 0.37:0.37     pbk
    igain     = 0.00:0.00     pbk
    ogain     = 1.00:1.00     pbk
    monitor   = 0.67:0.67     rec

Code and manuals

PIC microcontroller development on FreeBSD

Sun, 23 Jan 2022 00:00:00 +1200

Tested on FreeBSD 13.0. This article has also been mirrored on the FreeBSD Wiki.

Prerequisites

sdcc is a C compiler for microprocessors. It says that PIC microprocessors are unmaintained, but I’ve found it to be pretty reliable so far (take this with a grain of salt, I’m no expert). The port can be found under:

lang/sdcc

Page 75 of the sdcc user manual lists the supported PIC devices. Header files can be found under /usr/local/share/sdcc.

For programming the MCU, I’ve found pk2cmd to work alright with PICKit2 (or Chinese clones), but there’s no port for FreeBSD anymore. The Makefile won’t install files properly, so we have some extra work to do afterwards:

$ git clone https://github.com/psmay/pk2cmd.git
$ cd pk2cmd/pk2cmd
# gmake freebsd install clean
# mv /usr/share/pk2/PK2DeviceFile.dat /usr/local/bin
# rm -rf /usr/share/pk2

Supported devices for pk2cmd are listed here.

Detecting and programming the MCU

Avoid using just the -P option to auto-detect the MCU, as the VPP the PICKit2 applies to the chip trying to detect it can damage the MCU. Instead, use the chip number beforehand as shown below. Also, use the -C option to check if the chip is blank.

If any of the following pk2cmd commands fail, make sure everything really is wired properly:

$ pk2cmd -P PIC16F877A -C
Device is blank

Operation Succeeded

Compile your source code. The target executable is the .hex file sdcc will output. Replace pic14 and 16f877a with the appropriate names for your device:

$ sdcc --use-non-free -mpic14 -p16f877a main.c

Erase the PIC (if it wasn’t already blank) and flash the new code. Again, use the appropriate names:

$ pk2cmd -P PIC16F877A -E
$ pk2cmd -P PIC16F877A -X -M -F main.hex

If all went well, you should get an output similar to this:

PICkit 2 Program Report
23-1-2022, 21:01:29
Device Type: PIC16F877A

Program Succeeded.

Operation Succeeded

9front using bhyve(8) on FreeBSD

Tue, 23 Nov 2021 00:00:00 +1200

This article is also mirrored on the FreeBSD Wiki. and 9front Wiki.

Required ports:

sysutils/bhyve-firmware
sysutils/uefi-edk2-bhyve
sysutils/uefi-edk2-bhyve-csm
net/tigervnc-viewer

Add the following lines to /etc/rc.conf. Replace re0 with your own network interface. It’s good practice to assign each VM a unique tap interface in case you need to run multiple VMs at the same time. For simplicity’s sake, this setup uses only one tap:

if_bridge_load="YES"
if_tap_load="YES"
cloned_interfaces="bridge0 tap0"
ifconfig_bridge0="DHCP addm re0 addm tap0"
ifconfig_bridge0_alias0="inet 10.0.0.1/24"

Reboot your machine and then grab a 9front ISO.

Make a directory where you’ll store everything 9front-related. I usually keep all my bhyve(8) VMs under a ZFS dataset:

$ cd /path/to/vms/
$ mkdir 9front
$ mv /path/to/9front_iso 9front.iso

Create an empty file to be used as the VM’s hard drive. 10G will be more than enough:

$ truncate -s 10G disk.img

Make a startup script. Feel free to tweak the variable values to match your own setup. Obviously, when you’re done installing 9front from the ISO, you’ll be running the script without the -s 3,... line:

$ cat 9front_start

#!/bin/sh

name="9front"
cpu="2"
mem="2G"
iso="9front.iso"
disk="disk.img"
tap="tap0"

ifconfig ${tap} up

bhyve -c ${cpu} -m ${mem} -wH \
	-s 0,hostbridge \
	-s 3,ahci-cd,${iso} \
	-s 4,ahci-hd,${disk} \
	-s 5,virtio-net,${tap} \
	-s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \
	-s 30,xhci,tablet \
	-s 31,lpc \
	-l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \
	${name}

Make a shutdown script in order for bhyve(8) to shutdown properly:

$ cat 9front_stop

#!/bin/sh

name="9front"
tap="tap0"

ifconfig ${tap} down
bhyvectl --force-poweroff --vm=${name}
bhyvectl --destroy --vm=${name}

Make the scripts executable and start the VM:

$ chmod +x 9front_start 9front_stop
# ./9front_start; ./9front_stop

Run vncviewer(1) to connect to the VNC display:

$ vncviewer 0.0.0.0

When prompted for the monitor type during boot, choose xga.

OpenBSD Git server setup

Wed, 10 Feb 2021 00:00:00 +1200

Git subdomain

It’s good to have your Git server under a subdomain, so that it looks like git.example.org. To do that, add a new CNAME record for the subdomain on your registrar. If you’re on Epik, don’t forget the trailing period after the domain name.

Host: git | Points to: example.org.

Setting up the Git server

Install git:

# pkg_add git

First create a git user and give it a password. If you don’t want the same hosts that exist in your current user’s authorized_keys to have access to the Git server, then add their keys manually in the git user’s .ssh/authorized_keys file. In my case, it’s just me who has access to the server, so I will not edit anything:

# adduser git
...
# cp -r $HOME/.ssh /home/git/
# chown -R git:git /home/git/.ssh

Try sshing to the server as git from your local computer just to test if it works:

$ ssh git@example.org

If it worked, exit the session.

Set up a Git directory where all repositories will be stored at and cd into it:

# mkdir /var/www/htdocs/git.example.org
# chown -R git:git /var/www/htdocs/git.example.org
# cd /var/www/htdocs/git.example.org

Say I want to create a repository named repo. The structure your repositories should have is name.git, so in this case it’ll be repo.git. Create a bare repository inside it:

# mkdir repo.git
# git init --bare repo.git

Replace each text inside double quotes with what you want it to be:

# echo "John Doe" > repo.git/.git/owner
# echo "This is a repo" > repo.git/.git/description
# echo "git://git.example.org/repo.git" > repo.git/.git/url

To be able to interact with the Git server, the repository’s owner needs to be the git user you created earlier:

# chown -R git:git repo.git

Since sometimes the Git server by default might not be listening on port 9418 (the default Git port), which means that you’ll not be able to clone repositories from the Git server, you have to set up the daemon yourself using a massive git command. You can (in fact, you should) also use Git over HTTPS or SSH, but for now I’ll be using the default Git protocol for cloning and SSH for pushing.

# git daemon \
	--base-path=/var/www/htdocs/git.example.org/ \
	--export-all \
	--enable=receive-pack \
	--reuseaddr \
	--informative-errors \
	--verbose \
	--detach

Pushing changes to the server

On your local machine, make a repository for repo (the repository you created earlier) and add a few files so that you have something to commit and push to the server:

$ mkdir repo && cd repo
$ touch foo bar
$ git init
$ git add .
$ git commit -m "initial commit"

In order to be able to push you have to edit .git/config. If you’ve used GitHub before, you might have noticed that when you want to push, you push to origin; for this server I’ll use home, but you can use whatever else you want, it doesn’t really matter.

Append the following block to your repository’s .git/config and of course replace the domain and repository names with your own ones:

[remote "home"]
	url = git@git.example.org:/var/www/htdocs/git.example.org/repo.git
	fetch = +refs/heads/*:refs/remotes/home/*

Push to the Git server:

$ git push home master

Try also cloning the repository to make sure that everything works:

$ git clone git://git.example.org/repo.git

If that step was successful too, great, you now have a working Git server. :-)

Create a Web frontend with stagit(1).

OpenBSD Web server setup

Tue, 09 Feb 2021 00:00:00 +1200

HTTPS

acme-client(1) lets us have HTTPS.

Create the certificate directories:

# mkdir -p -m 700 /etc/ssl/private
# mkdir -p -m 755 /var/www/acme

Edit /etc/acme-client.conf. Replace example.org with your domain.

authority letsencrypt {
	api url "https://acme-v02.api.letsencrypt.org/directory"
	account key "/etc/ssl/private/letsencrypt.key"
}

domain example.org {
	domain key "/etc/ssl/private/example.org.key"
	domain certificate "/etc/ssl/example.org.crt"
	domain full chain certificate "/etc/ssl/example.org.pem"
	sign with letsencrypt
}

httpd(8)

OpenBSD already ships with a web server: httpd. You need to specify the following things:

The domain name.
Which port/s the server will listen to.
Where the website’s root directory is.

Create the website’s root directory. It should normally reside under /var/www/htdocs.

# mkdir -p /var/www/htdocs/example.org

The following configuration will suffice for now. With it you have HTTP and HTTPS for your website and it redirects HTTP to HTTPS automatically. If you want to learn more or see what other options and settings are available, read httpd.conf(5)’s man page. Inside /etc/httpd.conf we’ll write the following:

server "example.org" {
	listen on * port 80
	root "/htdocs/example.org"
	location "/.well-known/acme-challenge/*" {
		root "/acme"
		request strip 2
	}
	block return 301 "https://example.org$REQUEST_URI"
}

server "example.org" {
	listen on * tls port 443
	root "/htdocs/example.org"
	tls {
		certificate "/etc/ssl/example.org.pem"
		key "/etc/ssl/private/example.org.key"
	}
	location "/.well-known/acme-challenge/*" {
		root "/acme"
		request strip 2
	}
}

Generate the TLS certificates:

# acme-client -v example.org

Test to see if the configuration is correct:

# httpd -n

(Re)start the web server:

# rcctl restart httpd

Certificate renewal

TLS certificates expire after a few months so new certificates need to be generated when they expire. In order to avoid having to remember this and having to manually generate them, a cronjob will do it automatically:

# crontab -e

Append the following line:

0 0 * * * acme-client -v example.org && rcctl reload httpd

Arduino on FreeBSD

Wed, 28 Oct 2020 00:00:00 +1200

This article demonstrates how to develop for Arduino boards using only basic command line utilities, without having to use the Arduino IDE. The article has also been published on the FreeBSD Wiki.

Tested on FreeBSD 12.2 and above.

Prerequisites

Required ports:

devel/arduino-core
devel/arduino-bsd-mk
devel/avr-gcc
devel/avr-libc
devel/avrdude
comms/uarduno

With all the software installed, add the following line to /boot/loader.conf in case you want the Arduino kernel module to load automatically on boot. If you want to manually load the module whenever you need it, skip this step:

uarduno_load="YES"

Load the kernel module:

# kldload uarduno

Check your ~/.arduino/preferences.txt and see if the following lines exist (source):

serial.port=/dev/cuaU0
launcher=/usr/local/bin/firefox

Add your user to the dialer group:

# pw group mod dialer -m $USER

Connecting the board

Standard Arduino boards connect as /dev/cuaU0 and/or /dev/ttyU0 on FreeBSD. In case these serial ports don’t show up in /dev, you might need to press your board’s reset button. After you’ve plugged your board into a USB port, you should get the following output from dmesg. Although the output may vary, the important thing is that your board is connected and detected.

ugen1.5: <Arduino (www.arduino.cc) product 0x0043> at usbus1
uarduno0: <Arduino (www.arduino.cc) product 0x0043, class 2/0, rev 1.10/0.01, addr 5> on usbus1

If dmesg returned information about your board, you should also see cuaU0 and/or ttyU0 in /dev. In case your board is still not detected — considering it’s not a fake one, try using a different USB cable or reset it again and make sure you’ve followed the setup steps correctly.

The Makefile

The only thing you’re going to need in order to get started is just a Makefile that’ll be used to compile and upload your Arduino programs. Make a new directory for your Arduino project and a Makefile with the following lines:

ARDUINO_DIR= 	/usr/local/arduino
ARDUINO_MK_DIR= /usr/local/arduino-bsd-mk
#ARDUINO_LIBS=	
AVRDUDE_PORT=	your_board_port
ARDUINO_BOARD= 	your_board_name
SRCS=		your_source_files
TARGET=		your_program_name

include /usr/local/arduino-bsd-mk/bsd.arduino.mk

In my case my board is an Arduino Uno, so I’d have to set ARDUINO_BOARD to uno. You can see which other board types are available in /usr/local/arduino/hardware/arduino/avr/boards.txt. If you want to install new libraries, copy them over to /usr/local/arduino/hardware/arduino/avr/libraries/.

Avoid having source files named main.

Building and uploading a program

Write some Arduino code, and when you’re ready to compile and upload, run the following command:

# make install flash clean cleandepend

If all went well you should see the board executing the new code. If it doesn’t, try to see what errors the Makefile produced.

Monitoring

The Arduino IDE provides a serial monitor feature, but FreeBSD has a builtin monitoring utility which can be accessed directly from the terminal. Run this whenever you want to monitor your board and exit with ~! (use the appropriate port):

$ cu -l /dev/cuaU0

Using board types other than the Uno

As it’s mentioned above, we’re using the uarduno kernel module. Even though the module’s description is “FreeBSD Kernel Driver for the Arduino Uno USB interface”, you can, in fact, use different board types other than the Uno. According to uarduno’s website, you can modify /usr/ports/comms/uarduno/files/ids.txt to include more board types; the two fields are Vendor ID and Product ID. Read the comments inside the file for more information.

{ 0x2341, 0x0001 },  // Arduino UNO, vendor 2341H, product 0001H
{ 0x2341, 0x0042 },  // Arduino MEGA (rev 3), vendor 2341H, product 0042H
{ 0x2341, 0x0043 },  // Arduino UNO (rev 3), vendor 2341H, product 0043H
{ 0x2341, 0x0010 },  // Arduino MEGA 2560 R3, vendor 2341H, product 0010H 
{ 0x2341, 0x8037 },  // Arduino Micro

When you’re done, clean and re-build the port.

Known issues and their fixes

Even though you might have plugged your board to your machine, you might notice that there is no device appearing in /dev. Although there is no definite answer as to why this is happening, make sure that the USB cable is connected properly; on some boards, you have to hear a click sound.

When trying to use a new library, you might notice that your code doesn’t compile. A common issue is that you haven’t stored the library in the correct path. As mentioned, libraries are stored in /usr/local/arduino/hardware/arduino/avr/libraries/, so you have to move it there.

Christos Margiolis: bsd

PostgreSQL 15 and pgAdmin4 on FreeBSD

PostgreSQL

pgAdmin4

Upgrading pgAdmin4

Inline function tracing with the kinst DTrace provider

Table of Contents

Quick background

Usage

Inline function tracing

How it works

Syntactic transformations

Heuristic for calculating the entry and return offsets

Making a character device kernel module on FreeBSD

Table of contents

Implementing the device

malloc declaration

cdevsw structure

open() and close()

read() and write()

ioctl()

Creating and destroying the device

Module declaration

Makefile

Running the module

Testing

Share ZFS datasets with NFS

Host

Guest

Further reading

FreeBSD VNET Jails

Configuration

Installation

Delete jail

Further reading

FreeBSD sound mixer improvements

Table of contents

Kernel patches

Un/muting (commit)

Playback/recording mode information (commit)

Userland

mixer(3) implementation (commit)

mixer(8) rewrite (commit)

Code and manuals

PIC microcontroller development on FreeBSD

Prerequisites

Detecting and programming the MCU

9front using bhyve(8) on FreeBSD

OpenBSD Git server setup

Git subdomain

Setting up the Git server

Pushing changes to the server

OpenBSD Web server setup

HTTPS

httpd(8)

Certificate renewal

Arduino on FreeBSD

Prerequisites

Connecting the board

The Makefile

Building and uploading a program

Monitoring

Using board types other than the Uno

Known issues and their fixes

Heuristic for calculating the `entry` and `return` offsets

`cdevsw` structure