How to Write a System Daemon in C on FreeBSD

Learn how to write a system daemon in C on FreeBSD, covering basic concepts, advanced implementation techniques, and best practices.
by İbrahim Korucuoğlu ( @siberoloji) |
Tags:
Categories:

  10 minute read  

FreeBSD, one of the oldest and most stable Unix-like operating systems, provides a robust environment for developing system services. Daemons—processes that run in the background—are essential components of any Unix-like system. This guide will walk you through creating a custom system daemon in C on FreeBSD, covering everything from basic concepts to advanced implementation techniques.

Understanding Daemons in FreeBSD

A daemon is a background process that performs specific tasks without direct user interaction. Examples include httpd (web server), sshd (SSH server), and syslogd (system logging). Daemons typically:

  1. Fork from their parent process
  2. Become session leaders by creating a new session
  3. Change their working directory to the root (/)
  4. Close standard file descriptors
  5. Redirect standard file descriptors to /dev/null
  6. Run in the background indefinitely

FreeBSD’s daemon architecture follows traditional Unix principles but includes BSD-specific features and conventions.

Prerequisites

Before we begin, ensure you have:

  • FreeBSD (12.x or later recommended)
  • C compiler (Clang, which comes with FreeBSD)
  • Basic knowledge of C programming
  • Understanding of Unix/BSD system calls
  • Root/sudo access for system service integration

The development tools can be installed via:

pkg install gcc gmake git

Basic Daemon Structure

Let’s start with a skeleton daemon in C:

#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <errno.h>
#include <unistd.h>
#include <syslog.h>
#include <string.h>
#include <signal.h>

static void skeleton_daemon()
{
    pid_t pid;
    
    /* Fork off the parent process */
    pid = fork();
    
    /* An error occurred */
    if (pid < 0)
        exit(EXIT_FAILURE);
        
    /* Success: Let the parent terminate */
    if (pid > 0)
        exit(EXIT_SUCCESS);
        
    /* On success: The child process becomes session leader */
    if (setsid() < 0)
        exit(EXIT_FAILURE);
        
    /* Catch, ignore and handle signals */
    signal(SIGCHLD, SIG_IGN);
    signal(SIGHUP, SIG_IGN);
    
    /* Fork off for the second time */
    pid = fork();
    
    /* An error occurred */
    if (pid < 0)
        exit(EXIT_FAILURE);
        
    /* Success: Let the parent terminate */
    if (pid > 0)
        exit(EXIT_SUCCESS);
        
    /* Set new file permissions */
    umask(0);
    
    /* Change the working directory to the root directory */
    chdir("/");
    
    /* Close all open file descriptors */
    int x;
    for (x = sysconf(_SC_OPEN_MAX); x >= 0; x--)
    {
        close(x);
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
}

int main()
{
    skeleton_daemon();
    
    while (1)
    {
        /* Do some task here */
        syslog(LOG_NOTICE, "Daemon is running...");
        sleep(30); /* Sleep for 30 seconds */
    }
    
    return EXIT_SUCCESS;
}

FreeBSD-Specific Daemonization

FreeBSD provides a convenient function called daemon() in its standard library, which performs the typical daemonization steps. Using this function simplifies our code significantly:

#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>
#include <signal.h>

int main()
{
    /* Daemonize the process */
    if (daemon(0, 0) != 0) {
        return EXIT_FAILURE;
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
    syslog(LOG_NOTICE, "Daemon started");
    
    /* Main loop */
    while (1)
    {
        syslog(LOG_NOTICE, "Daemon is running...");
        sleep(30);
    }
    
    return EXIT_SUCCESS;
}

The daemon(0, 0) call performs all the daemonization steps we did manually in the first example. The two parameters control whether the daemon changes to the root directory (0 = yes) and whether it closes standard file descriptors (0 = yes).

Adding Signal Handling

A proper daemon should handle signals gracefully. Let’s add signal handlers for SIGTERM and SIGHUP:

#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>
#include <signal.h>
#include <stdio.h>
#include <stdbool.h>

volatile bool running = true;

/* Signal handler for termination signals */
void handle_signal(int sig)
{
    switch (sig) {
        case SIGTERM:
            syslog(LOG_NOTICE, "Received SIGTERM, shutting down...");
            running = false;
            break;
        case SIGHUP:
            syslog(LOG_NOTICE, "Received SIGHUP, reloading configuration...");
            /* Code to reload configuration would go here */
            break;
    }
}

int main()
{
    /* Set up signal handling before daemonizing */
    signal(SIGTERM, handle_signal);
    signal(SIGHUP, handle_signal);
    
    /* Daemonize the process */
    if (daemon(0, 0) != 0) {
        perror("daemon");
        return EXIT_FAILURE;
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
    syslog(LOG_NOTICE, "Daemon started");
    
    /* Main loop */
    while (running)
    {
        syslog(LOG_NOTICE, "Daemon is running...");
        sleep(30);
    }
    
    syslog(LOG_NOTICE, "Daemon shutting down");
    closelog();
    
    return EXIT_SUCCESS;
}

PID File Management

For system integration, daemons typically create a PID file that stores the process ID. This allows other programs to send signals to the daemon:

#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>
#include <signal.h>
#include <stdio.h>
#include <stdbool.h>
#include <fcntl.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>

#define PID_FILE "/var/run/mydaemon.pid"

volatile bool running = true;

void handle_signal(int sig)
{
    switch (sig) {
        case SIGTERM:
            syslog(LOG_NOTICE, "Received SIGTERM, shutting down...");
            running = false;
            break;
        case SIGHUP:
            syslog(LOG_NOTICE, "Received SIGHUP, reloading configuration...");
            /* Code to reload configuration would go here */
            break;
    }
}

int write_pid_file()
{
    char buf[32];
    int fd;
    
    fd = open(PID_FILE, O_RDWR | O_CREAT, 0640);
    if (fd < 0) {
        syslog(LOG_ERR, "Could not open PID file %s: %s", PID_FILE, strerror(errno));
        return -1;
    }
    
    if (lockf(fd, F_TLOCK, 0) < 0) {
        syslog(LOG_ERR, "Could not lock PID file %s: %s", PID_FILE, strerror(errno));
        close(fd);
        return -1;
    }
    
    /* Write PID to file */
    sprintf(buf, "%d\n", getpid());
    if (write(fd, buf, strlen(buf)) < 0) {
        syslog(LOG_ERR, "Could not write to PID file %s: %s", PID_FILE, strerror(errno));
        close(fd);
        return -1;
    }
    
    /* Keep file open to maintain lock */
    return fd;
}

int main()
{
    int pid_fd;
    
    /* Set up signal handling before daemonizing */
    signal(SIGTERM, handle_signal);
    signal(SIGHUP, handle_signal);
    
    /* Daemonize the process */
    if (daemon(0, 0) != 0) {
        perror("daemon");
        return EXIT_FAILURE;
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
    syslog(LOG_NOTICE, "Daemon started");
    
    /* Write PID file */
    pid_fd = write_pid_file();
    if (pid_fd < 0) {
        syslog(LOG_ERR, "Failed to create PID file");
        return EXIT_FAILURE;
    }
    
    /* Main loop */
    while (running)
    {
        syslog(LOG_NOTICE, "Daemon is running...");
        sleep(30);
    }
    
    syslog(LOG_NOTICE, "Daemon shutting down");
    
    /* Clean up PID file */
    if (pid_fd >= 0) {
        close(pid_fd);
        unlink(PID_FILE);
    }
    
    closelog();
    
    return EXIT_SUCCESS;
}

Adding Configuration File Support

Let’s enhance our daemon with configuration file support using FreeBSD’s libucl (Universal Configuration Language):

#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>
#include <signal.h>
#include <stdio.h>
#include <stdbool.h>
#include <fcntl.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>
#include <ucl.h>

#define PID_FILE "/var/run/mydaemon.pid"
#define CONFIG_FILE "/usr/local/etc/mydaemon.conf"

volatile bool running = true;
int interval = 30; /* Default interval */

/* Structure to hold configuration */
struct config {
    int interval;
    char log_level[10];
};

/* Load configuration from file */
int load_config(struct config *cfg)
{
    struct ucl_parser *parser;
    ucl_object_t *obj = NULL;
    const ucl_object_t *value;
    
    parser = ucl_parser_new(0);
    if (!parser) {
        syslog(LOG_ERR, "Failed to allocate UCL parser");
        return -1;
    }
    
    if (!ucl_parser_add_file(parser, CONFIG_FILE)) {
        syslog(LOG_ERR, "Failed to parse config file: %s", 
               ucl_parser_get_error(parser));
        ucl_parser_free(parser);
        return -1;
    }
    
    obj = ucl_parser_get_object(parser);
    ucl_parser_free(parser);
    
    if (!obj) {
        syslog(LOG_ERR, "Failed to get UCL object from parser");
        return -1;
    }
    
    /* Get interval value */
    value = ucl_object_lookup(obj, "interval");
    if (value && ucl_object_type(value) == UCL_INT) {
        cfg->interval = ucl_object_toint(value);
    } else {
        cfg->interval = 30; /* Default value */
    }
    
    /* Get log level value */
    value = ucl_object_lookup(obj, "log_level");
    if (value && ucl_object_type(value) == UCL_STRING) {
        strncpy(cfg->log_level, ucl_object_tostring(value), sizeof(cfg->log_level) - 1);
        cfg->log_level[sizeof(cfg->log_level) - 1] = '\0';
    } else {
        strcpy(cfg->log_level, "notice"); /* Default value */
    }
    
    ucl_object_unref(obj);
    return 0;
}

void handle_signal(int sig)
{
    switch (sig) {
        case SIGTERM:
            syslog(LOG_NOTICE, "Received SIGTERM, shutting down...");
            running = false;
            break;
        case SIGHUP:
            syslog(LOG_NOTICE, "Received SIGHUP, reloading configuration...");
            struct config cfg;
            if (load_config(&cfg) == 0) {
                interval = cfg.interval;
                syslog(LOG_NOTICE, "Configuration reloaded, new interval: %d", interval);
            }
            break;
    }
}

int write_pid_file()
{
    /* Implementation remains the same as before */
}

int main()
{
    int pid_fd;
    struct config cfg;
    
    /* Set up signal handling before daemonizing */
    signal(SIGTERM, handle_signal);
    signal(SIGHUP, handle_signal);
    
    /* Load initial configuration */
    if (load_config(&cfg) == 0) {
        interval = cfg.interval;
        syslog(LOG_NOTICE, "Loaded configuration, interval: %d", interval);
    }
    
    /* Daemonize the process */
    if (daemon(0, 0) != 0) {
        perror("daemon");
        return EXIT_FAILURE;
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
    syslog(LOG_NOTICE, "Daemon started");
    
    /* Write PID file */
    pid_fd = write_pid_file();
    if (pid_fd < 0) {
        syslog(LOG_ERR, "Failed to create PID file");
        return EXIT_FAILURE;
    }
    
    /* Main loop */
    while (running)
    {
        syslog(LOG_NOTICE, "Daemon is running...");
        sleep(interval);
    }
    
    syslog(LOG_NOTICE, "Daemon shutting down");
    
    /* Clean up PID file */
    if (pid_fd >= 0) {
        close(pid_fd);
        unlink(PID_FILE);
    }
    
    closelog();
    
    return EXIT_SUCCESS;
}

Note: To use libucl, you’ll need to install it first:

pkg install libucl

And compile with:

cc -o mydaemon mydaemon.c -lucl

Creating a RC Script for System Integration

FreeBSD uses RC scripts for service management. Let’s create an RC script for our daemon:

#!/bin/sh
#
# PROVIDE: mydaemon
# REQUIRE: NETWORKING syslogd
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf to enable mydaemon:
# mydaemon_enable="YES"
# mydaemon_flags="" # Optional flags

. /etc/rc.subr

name="mydaemon"
rcvar="mydaemon_enable"

load_rc_config $name

: ${mydaemon_enable:="NO"}
: ${mydaemon_flags:=""}

pidfile="/var/run/${name}.pid"
command="/usr/local/sbin/${name}"
command_args="${mydaemon_flags}"

run_rc_command "$1"

Save this file as /usr/local/etc/rc.d/mydaemon, then make it executable:

chmod +x /usr/local/etc/rc.d/mydaemon

To enable the daemon at boot time, add this line to /etc/rc.conf:

mydaemon_enable="YES"

Advanced Topic: Using kqueue for Event Handling

FreeBSD’s kqueue is a powerful event notification interface. Let’s modify our daemon to use kqueue:

#include <stdlib.h>
#include <unistd.h>
#include <syslog.h>
#include <signal.h>
#include <stdio.h>
#include <stdbool.h>
#include <fcntl.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>
#include <sys/event.h>
#include <sys/time.h>

#define PID_FILE "/var/run/mydaemon.pid"

volatile bool running = true;

void handle_signal(int sig)
{
    switch (sig) {
        case SIGTERM:
            syslog(LOG_NOTICE, "Received SIGTERM, shutting down...");
            running = false;
            break;
        case SIGHUP:
            syslog(LOG_NOTICE, "Received SIGHUP, reloading configuration...");
            /* Code to reload configuration would go here */
            break;
    }
}

int write_pid_file()
{
    /* Implementation remains the same as before */
}

int main()
{
    int pid_fd, kq;
    struct kevent change_event[2];
    struct kevent event;
    
    /* Set up signal handling before daemonizing */
    signal(SIGTERM, SIG_IGN); /* Ignore these signals initially */
    signal(SIGHUP, SIG_IGN);  /* We'll handle them via kqueue */
    
    /* Daemonize the process */
    if (daemon(0, 0) != 0) {
        perror("daemon");
        return EXIT_FAILURE;
    }
    
    /* Open logs for writing */
    openlog("mydaemon", LOG_PID, LOG_DAEMON);
    syslog(LOG_NOTICE, "Daemon started");
    
    /* Write PID file */
    pid_fd = write_pid_file();
    if (pid_fd < 0) {
        syslog(LOG_ERR, "Failed to create PID file");
        return EXIT_FAILURE;
    }
    
    /* Create kqueue */
    kq = kqueue();
    if (kq == -1) {
        syslog(LOG_ERR, "kqueue() failed: %s", strerror(errno));
        return EXIT_FAILURE;
    }
    
    /* Set up event for SIGTERM */
    EV_SET(&change_event[0], SIGTERM, EVFILT_SIGNAL, EV_ADD, 0, 0, NULL);
    
    /* Set up event for SIGHUP */
    EV_SET(&change_event[1], SIGHUP, EVFILT_SIGNAL, EV_ADD, 0, 0, NULL);
    
    /* Register for both signals */
    if (kevent(kq, change_event, 2, NULL, 0, NULL) == -1) {
        syslog(LOG_ERR, "kevent register failed: %s", strerror(errno));
        return EXIT_FAILURE;
    }
    
    /* Main loop using kqueue for events */
    while (running)
    {
        /* Timer event for our regular task */
        struct timespec timeout = { 30, 0 }; /* 30 seconds */
        
        int ret = kevent(kq, NULL, 0, &event, 1, &timeout);
        
        if (ret == -1) {
            syslog(LOG_ERR, "kevent wait failed: %s", strerror(errno));
            break;
        } else if (ret > 0) {
            /* We got an event */
            if (event.filter == EVFILT_SIGNAL) {
                /* Handle signals */
                if (event.ident == SIGTERM) {
                    syslog(LOG_NOTICE, "Received SIGTERM via kqueue, shutting down...");
                    running = false;
                } else if (event.ident == SIGHUP) {
                    syslog(LOG_NOTICE, "Received SIGHUP via kqueue, reloading configuration...");
                    /* Code to reload configuration would go here */
                }
            }
        } else {
            /* Timeout occurred, do our regular task */
            syslog(LOG_NOTICE, "Daemon is running...");
        }
    }
    
    syslog(LOG_NOTICE, "Daemon shutting down");
    
    /* Clean up PID file */
    if (pid_fd >= 0) {
        close(pid_fd);
        unlink(PID_FILE);
    }
    
    closelog();
    
    return EXIT_SUCCESS;
}

Conclusion

Creating daemons in FreeBSD follows the Unix tradition with some BSD-specific enhancements. This guide has walked you through the process from basic daemonization to advanced features like signal handling, configuration management, and event notification with kqueue.

To create a robust production daemon, consider adding:

  1. Proper logging with log rotation
  2. Privilege dropping (running as non-root user)
  3. Resource limits using setrlimit()
  4. Sandboxing using Capsicum capability mode
  5. Comprehensive error handling and recovery
  6. Monitoring integration

FreeBSD’s robust architecture makes it an excellent platform for developing system services. By following these principles and best practices, you can create reliable, efficient daemons that integrate seamlessly with the FreeBSD operating system.


< Using Git for Version Control on FreeBSDHow to Package Software for pkg Using poudriere on FreeBSD >