Signals in prod: dangers and pitfalls

In this blog post, Chris Down, a Kernel Engineer at Meta, discusses the pitfalls of using Linux signals in Linux production environments and why developers should avoid using signals whenever possible.

What are Linux Signals?

A signal is an event that Linux systems generate in response to some condition. Signals can be sent by the kernel to a process, by a process to another process, or a process to itself. Upon receipt of a signal, a process may take action.

Signals are a core part of Unix-like operating environments and have existed since more or less the dawn of time. They are the plumbing for many of the core components of the operating system—core dumping, process life cycle management, etc.—and in general, they've held up pretty well in the fifty or so years that we have been using them. As such, when somebody suggests that using them for interprocess communication (IPC) is potentially dangerous, one might think these are the ramblings of someone desperate to invent the wheel. However, this article is intended to demonstrate cases where signals have been the cause of production issues and offer some potential mitigations and alternatives.

Signals may appear attractive due to their standardization, wide availability and the fact that they don’t require any additional dependencies outside of what the operating system provides. However, they can be difficult to use safely. Signals make a vast number of assumptions which one must be careful to validate to match their requirements, and if not, one must be careful to configure correctly. In reality, many applications, even widely known ones, do not do so, and may have hard-to-debug incidents in the future as a result.

Let us look into a recent incident that occurred in the Meta production environment, reinforcing the pitfalls of using signals. We’ll go briefly over the history of some signals and how they led us to where we are today, and then we’ll contrast that with our current needs and issues that we’re seeing in production.

The Incident

First, let's rewind a bit. The LogDevice team cleaned up their codebase, removing unused code and features. One of the features that was deprecated was a type of log that documents certain operations performed by the service. This feature eventually became redundant, had no consumers and as such was removed. You can see the change here on GitHub. So far, so good.

The next little while after the change passed without much to speak about, production continued ticking on steadily and serving traffic as usual. A few weeks later, a report that service nodes were being lost at a staggering rate was received. It was something to do with the rollout of the new release, but what exactly was wrong was unclear. What was different now that had caused things to fall over?

The team in question narrowed the problem to the code change we mentioned earlier, deprecating these logs. But why? What's wrong with that code? If you don't already know the answer, we invite you to look at that diff and try to work out what's wrong because it’s not immediately obvious, and it’s a mistake anyone could make.

logrotate, Enter the Ring

logrotate is more or less the standard tool for log rotation when using Linux. It's been around for almost thirty years now, and the concept is simple: manage the life cycle of logs by rotating and vacuuming them.

logrotate doesn't send any signals by itself, so you won't find much, if anything, about them in the logrotate main page or its documentation. However, logrotate can take arbitrary commands to execute before or after its rotations. Just as a basic example from the default logrotate configuration in CentOS, you can see this configuration:

/var/log/cron
/var/log/maillog
/var/log/messages
/var/log/secure
/var/log/spooler
{
    sharedscripts
    postrotate
        /bin/kill -HUP `cat /var/run/syslogd.pid 2> /dev/null` 2> /dev/null || true
    endscript
}

A bit brittle, but we'll forgive that and assume that this works as intended. This configuration says that after logrotate rotates any of the files listed, it should send SIGHUP to the pid contained in /var/run/syslogd.pid, which should be that of the running syslogd instance.

This is all well and good for something with a stable public API like syslog, but what about something internal where the implementation of SIGHUP is an internal implementation detail that could change at any time?

A History of Hangups

One of the problems here is that, except for signals which cannot be caught in user space and thus have only one meaning, like SIGKILL and SIGSTOP, the semantic meaning of signals is up to application developers and users to interpret and program. In some cases, the distinction is largely academic, like SIGTERM, which is pretty much universally understood to mean "terminate gracefully as soon as possible." However, in the case of SIGHUP, the meaning is significantly less clear.

SIGHUP was invented for serial lines and was originally used to indicate that the other end of the connection had dropped the line. Nowadays, we still carry our lineage with us of course, so SIGHUP is still sent for its modern equivalent: where a pseudo or virtual terminal is closed (hence tools like nohup, which mask it).

In the early days of Unix, there was a need to implement daemon reloading. This usually consists at least of configuration/log file reopening without restarting, and signals seemed like a dependency-free way to achieve that. Of course, there was no signal for such a thing, but as these daemons have no controlling terminal, there should be no reason to receive SIGHUP, so it seemed like a convenient signal to piggyback onto without any obvious side effects.

There is a small hitch with this plan though. The default state for signals is not "ignored," but signal-specific. So, for example, programs don't have to configure SIGTERM manually to terminate their application. As long as they don't set any other signal handler, the kernel just terminates their program for free, without any code needed in user space. Convenient!

What's not so convenient though, is that SIGHUP also has the default behavior of terminating the program immediately. This works great for the original hangup case, where these applications likely aren't needed anymore, but is not so great for this new meaning.

This would be fine of course, if we removed all the places which could potentially send SIGHUP to the program. The problem is that in any large, mature codebase, that is difficult. SIGHUP is not like a tightly controlled IPC call for which you can easily grep the codebase for. Signals can come from anywhere, at any time, and there are few checks on their operation (other than the most basic "are you this user or have CAP_KILL"). The bottom line is that it's hard to determine where signals could come from, but with more explicit IPC, we would know that this signal doesn't mean anything to us and should be ignored.

From Hangup to Hazard

By now, I suppose you may have started to guess what happened. A LogDevice release started one fateful afternoon containing the aforementioned code change. At first, nothing had gone awry, but at midnight the next day, everything mysteriously started falling over. The reason is the following stanza in the machine's logrotate configuration, which sends a now unhandled (and therefore fatal) SIGHUP to the logdevice daemon:

/var/log/logdevice/audit.log {
  daily
  # [...]
  postrotate
    pkill -HUP logdeviced
  endscript
}

Missing just one short stanza of a logrotate configuration is incredibly easy and common when removing a large feature. Unfortunately, it’s also hard to be certain that every last vestige of its existence was removed at once. Even in cases that are easier to validate than this, it’s common to mistakenly leave remnants when doing code cleanup. Still, usually, it's without any destructive consequences, that is, the remaining detritus is just dead or no-op code.

Conceptually, the incident itself and its resolution are simple: don't send SIGHUP, and spread LogDevice actions out more over time (that is, don’t run this at midnight on the dot). However, it's not just this one incident's nuances that we should focus on here. This incident, more than anything, has to serve as a platform to discourage the use of signals in production for anything other than the most basic, essential cases.

The Dangers of Signals

What Signals are Good For

First, using signals as a mechanism to affect changes in the process state of the operating system is well founded. This includes signals like SIGKILL, which are impossible to install a signal handler for and does exactly what you would expect, and the kernel-default behavior of SIGABRT, SIGTERM, SIGINT, SIGSEGV, and SIGQUIT and the like, which are generally well understood by users and programmers.

What these signals all have in common is that once you’ve received them, they're all progressing towards a terminal end state within the kernel itself. That is, no more user space instructions will be executed once you get a SIGKILL or SIGTERM with no user space signal handler.

A terminal end state is important because it usually means you're working towards decreasing the complexity of the stack and code currently being executed. Other desired states often result in the complexity actually becoming higher and harder to reason about as concurrency and code flow become more muddled.

Dangerous Default Behavior

You may notice that we didn't mention some other signals that also terminate by default. Here's a list of all of the standard signals that terminate by default (excluding core dump signals like SIGABRT or SIGSEGV, since they're all sensible):

• SIGALRM
• SIGEMT
• SIGHUP
• SIGINT
• SIGIO
• SIGKILL
• SIGLOST
• SIGPIPE
• SIGPOLL
• SIGPROF
• SIGPWR
• SIGSTKFLT
• SIGTERM
• SIGUSR1
• SIGUSR2
• SIGVTALRM

At first glance, these may seem reasonable, but here are a few outliers:

• SIGHUP: If this was used only as it was originally intended, defaulting to terminate would be sensible. With the current mixed usage meaning “reopen files,” this is dangerous.
• SIGPOLL and SIGPROF: These are in the bucket of "these should be handled internally by some standard function rather than your program." However, while probably harmless, the default behavior to terminate still seems nonideal.
• SIGUSR1 and SIGUSR2: These are "user-defined signals" that you can ostensibly use however you like. But because these are terminal by default, if you implement USR1 for some specific need and later don't need that, you can't just safely remove the code. You have to consciously think to explicitly ignore the signal. That's really not going to be obvious even to every experienced programmer.

So that's almost one-third of terminal signals, which are at best questionable and, at worst, actively dangerous as a program's needs change. Worse still, even the supposedly "user-defined" signals are a disaster waiting to happen when someone forgets to explicitly SIG_IGN it. Even an innocuous SIGUSR1 or SIGPOLL may cause incidents.

This is not simply a question of familiarity. No matter how well you know how signals work, it’s still extremely hard to write signal-correct code the first time around because, despite their appearance, signals are far more complex than they seem.

Code flow, Concurrency, and the Myth of SA_RESTART

Programmers generally do not spend their entire day thinking about the inner workings of signals. This means that when it comes to actually implementing signal handling, they often subtly do the wrong thing.

I'm not even talking about the "trivial" cases, like safety in a signal handling function, which is mostly solved by only bumping a sig_atomic_t, or using C++'s atomic signal fence stuff. No, that's mostly easily searchable and memorable as a pitfall by anyone after their first time through signal hell. What's a lot harder is reasoning about the code flow of the nominal portions of a complex program when it receives a signal. Doing so requires either constantly and explicitly thinking about signals at every part of the application life cycle (hey, what about EINTR, is SA_RESTART enough here? What flow should we go into if this terminates prematurely? I now have a concurrent program, what are the implications of that?), or setting up a sigprocmask or pthread_setmask for some part of your application life cycle and praying that the code flow never changes (which is certainly not a good guess in an atmosphere of fast-paced development). signalfd or running sigwaitinfo in a dedicated thread can help somewhat here, but both of these have enough edge cases and usability concerns to make them hard to recommend.

We like to believe that most experienced programmers know by now that even a facetious example of correctly writing thread-safe code is very hard. Well, if you thought correctly writing thread-safe code was hard, signals are significantly harder. Signal handlers must only rely on strictly lock-free code with atomic data structures, respectively, because the main flow of execution is suspended and we don't know what locks it's holding, and because the main flow of execution could be performing non-atomic operations. They must also be fully reentrant, that is, they must be able to nest within themselves since signal handlers can overlap if a signal is sent multiple times (or even with one signal, with SA_NODEFER). That's one of the reasons why you can't use functions like printf or malloc in a signal handler because they rely on global mutexes for synchronization. If you were holding that lock when the signal was received and then called a function requiring that lock again, your application would end up deadlocked. This is really, really hard to reason about. That's why many people simply write something like the following as their signal handling:

static volatile sig_atomic_t received_sighup; 

static void sighup(int sig __attribute__((unused))) { received_sighup = 1; }

static int configure_signal_handlers(void) {
  return sigaction(
    SIGHUP,
    &(const struct sigaction){.sa_handler = sighup, .sa_flags = SA_RESTART},
    NULL);
}

int main(int argc, char *argv[]) {
  if (configure_signal_handlers()) {
       /* failed to set handlers */
  }

  /* usual program flow */

  if (received_sighup) {
    /* reload */
    received_sighup = 0;
  }

  /* usual program flow */
}

The problem is that, while this, signalfd, or other attempts at async signal handling might look fairly simple and robust, it ignores the fact that the point of interruption is just as important as the actions performed after receiving the signal. For example, suppose your user space code is doing I/O or changing the metadata of objects that come from the kernel (like inodes or FDs). In this case, you're probably actually in a kernel space stack at the time of interruption. For example, here's how a thread might look when it's trying to close a file descriptor:

# cat /proc/2965230/stack
 [<0>] schedule+0x43/0xd0
 [<0>] io_schedule+0x12/0x40
 [<0>] wait_on_page_bit+0x139/0x230
 [<0>] filemap_write_and_wait+0x5a/0x90
 [<0>] filp_close+0x32/0x70
 [<0>] __x64_sys_close+0x1e/0x50
 [<0>] do_syscall_64+0x4e/0x140
 [<0>] entry_SYSCALL_64_after_hwframe+0x44/0xa9

Here, __x64_sys_close is the x86_64 variant of the close system call, which closes a file descriptor. At this point in its execution, we're waiting for the backing storage to be updated (that's this wait_on_page_bit). Since I/O work is usually several orders of magnitude slower than other operations, schedule here is a way of voluntarily hinting to the kernel's CPU scheduler that we are about to perform a high-latency operation (like disk or network I/O) and that it should consider finding another process to schedule instead of the current process for now. This is good, as it allows us to signal to the kernel that it is a good idea to go ahead and pick a process that will actually make use of the CPU instead of wasting time on one which can't continue until it's finished waiting for a response from something that may take a while.

Imagine that we send a signal to the process we were running. The signal that we have sent has a user space handler in the receiving thread, so we'll resume in user space. One of the many ways this race can end up is that the kernel will try to come out of schedule, further unwind the stack and eventually return an errno of ESYSRESTART or EINTR to user space to indicate that we were interrupted. But how far did we get in closing it? What's the state of the file descriptor now?

Now that we’ve returned to user space, we'll run the signal handler. When the signal handler exits, we'll propagate the error to the user space libc's close wrapper, and then to the application, which, in theory, can do something about the situation encountered. We say "in theory" because it's really hard to know what to do about many of these situations with signals, and many services in production do not handle the edge cases here very well. That might be fine in some applications where data integrity isn't that important. However, in production applications that do care about data consistency and integrity, this presents a significant problem: the kernel doesn't expose any granular way to understand how far it got, what it achieved and didn't and what we should actually do about the situation. Even worse, if close returns with EINTR, the state of the file descriptor is now unspecified:

Good luck trying to reason about how to handle that safely and securely in your application. In general, handling EINTR even for well-behaved syscalls is complicated. There are plenty of subtle issues forming a large part of the reason why SA_RESTART is not enough. Not all system calls are restartable, and expecting every single one of your application's developers to understand and mitigate the deep nuances of getting a signal for every single syscall at every single call site is asking for outages. From man 7 signal:

Likewise, using a sigprocmask and expecting code flow to remain static is asking for trouble as developers do not typically spend their lives thinking about the bounds of signal handling or how to produce or preserve signal-correct code. The same goes for handling signals in a dedicated thread with sigwaitinfo, which can easily end up with GDB and similar tools being unable to debug the process. Subtly wrong code flows or error handling can result in bugs, crashes, difficult to debug corruptions, deadlocks and many more issues that will send you running straight into the warm embrace of your preferred incident management tool.

High Complexity in Multithreaded Environments

If you thought all this talk of concurrency, reentrancy and atomicity was bad enough, throwing multithreading into the mix makes things even more complicated. This is especially important when considering the fact that many complex applications run separate threads implicitly, for example, as part of jemalloc, GLib, or similar. Some of these libraries even install signal handlers themselves, opening a whole other can of worms.

Overall, man 7 signal has this to say on the matter:

More succinctly, "for most signals, the kernel sends the signal to any thread that doesn't have that signal blocked with sigprocmask". SIGSEGV, SIGILL and the like resemble traps, and have the signal explicitly directed at the offending thread. However, despite what one might think, most signals cannot be explicitly sent to a single thread in a thread group, even with tgkill or pthread_kill.

This means that you can't trivially change overall signal handling characteristics as soon as you have a set of threads. If a service needs to do periodic signal blocking with sigprocmask in the main thread, you need to somehow communicate to other threads externally about how they should handle that. Otherwise, the signal may be swallowed by another thread, never to be seen again. Of course, you can block signals in child threads to avoid this, but if they need to do their own signal handling, even for primitive things like waitpid, it will end up making things complex.

Just as with everything else here, these aren't technically insurmountable problems. However, one would be negligent in ignoring the fact that the complexity of synchronization required to make this work correctly is burdensome and lays the groundwork for bugs, confusion and worse.

Lack of Definition and Communication of Success or Failure

Signals are propagated asynchronously in the kernel. The kill syscall returns as soon as the pending signal is recorded for the process or thread’s task_struct in question. Thus, there's no guarantee of timely delivery, even if the signal isn't blocked.

Even if there is timely delivery of the signal, there’s no way to communicate back to the signal issuer what the status of their request for action is. As such, any meaningful action should not be delivered by signals, since they only implement fire-and-forget with no real mechanism to report the success or failure of delivery and subsequent actions. As we’ve seen above, even seemingly innocuous signals can be dangerous when they are not configured in user space.

Anyone using Linux for long enough has undoubtedly run into a case where they want to kill some process but find that the process is unresponsive even to supposedly always fatal signals like SIGKILL. The problem is that misleadingly, kill(1)’s purpose isn’t to kill processes, but just to queue a request to the kernel (with no indication about when it will be serviced) that someone has requested some action to be taken.

The kill syscall’s job is to mark the signal as pending in the kernel's task metadata, which it does successfully even when a SIGKILL task doesn’t die. In the case of SIGKILL in particular, the kernel guarantees that no more user mode instructions will be executed, but we may still have to execute instructions in kernel mode to complete actions that otherwise may result in data corruption or to release resources. For this reason, we still succeed even if the state is D (uninterruptible sleep). Kill itself doesn't fail unless you provided an invalid signal, you don't have permission to send that signal or the pid that you requested to send a signal to does not exist and is thus not useful to reliably propagate non-terminal states to applications.

In Conclusion

• Signals are fine for terminal state handled purely in-kernel with no user space handler. For signals that you actually would like to immediately kill your program, leave those signals alone for the kernel to handle. This also means that the kernel may be able to exit early from its work, freeing up your program resources more quickly, whereas a user space IPC request would have to wait for the user space portion to start executing again.

• A way to avoid getting into trouble handling signals is to not handle them at all. However, for applications handling state processing that must do something about cases like SIGTERM, ideally use a high-level API like folly::AsyncSignalHandler where a number of the warts have already been made more intuitive.

• Avoid communicating application requests with signals. Use self-managed notifications (like inotify) or user space RPC with a dedicated part of the application life cycle to handle it instead of relying on interrupting the application.
• Where possible, limit the scope of signals to a subsection of your program or threads with sigprocmask, reducing the amount of code that needs to be regularly scrutinized for signal-correctness. Bear in mind that if code flows or threading strategies change, the mask may not have the effect you intended.
• At daemon start, mask terminal signals that are not uniformly understood and could be repurposed at some point in your program to avoid falling back to kernel default behavior. My suggestion is the following:

signal(SIGHUP, SIG_IGN);
signal(SIGQUIT, SIG_IGN);
signal(SIGUSR1, SIG_IGN);
signal(SIGUSR2, SIG_IGN);

Signal behavior is extremely complicated to reason about even in well-authored programs, and its use presents an unnecessary risk in applications where other alternatives are available. In general, do not use signals for communicating with the user space portion of your program. Instead, either have the program transparently handle events itself (for example, with inotify), or use user space communication that can report back errors to the issuer and is enumerable and demonstrable at compile time, like Thrift, gRPC or similar.

I hope this article has shown you that signals, while they may ostensibly appear simple, are in reality anything but. The aesthetics of simplicity that promote their use as an API for user space software belie a series of implicit design decisions that do not fit most production use cases in the modern era.

Let’s be clear: there are valid use cases for signals. Signals are fine for basic communication with the kernel about a desired process state when there’s no user space component, for example, that a process should be killed. However, it is difficult to write signal-correct code the first time around when signals are expected to be trapped in user space.

Signals may seem attractive due to their standardization, wide availability and lack of dependencies, but they come with a significant number of pitfalls that will only increase concern as your project grows. Hopefully, this article has provided you with some mitigations and alternative strategies that will allow you to still achieve your goals, but in a safer, less subtly complex and more intuitive way.

To learn more about Meta Open Source, visit our open source site, subscribe to our YouTube channel, or follow us on Twitter, Facebook and LinkedIn.