Unix Sockets

News	See Also	Recommended Links	Pipes	Sockets	Nmap
ntop	ngrep	nettee	Netcat	Humor	Etc

Remember FIFOs? Remember how they can only send data in one direction, just like a Pipes? Wouldn't it be grand if you could send data in both directions. In other works operate with network connection in a manner close to file.

Unix Domain Sockets is a two-way communications pipe. This family of sockets is for local communication only, i.e. you cannot use them across a network. Please see Beej's Guide to Network Programming Using Internet Sockets about Internet sockets.

Unix sockets are a special file in the file system (just like FIFOs) but for historical reasons instead of using open() and read() you'll be using socket(), bind(), recv(), etc. The telephone analogy is a very good one and greatly simplify understanding socket behavior.

When programming with sockets, you'll usually create server and client programs. The server will sit listening for incoming connections from clients and handle them.

For instance, when describing which Unix socket you want to use (that is, the path to the special file that is the socket), you use a struct sockaddr_un, which has the following fields:

    struct sockaddr_un {
        unsigned short sun_family;  /* AF_UNIX */
        char sun_path[108];
    }

This is the structure you will be passing to the bind() function, which associates a socket descriptor (a file descriptor) with a certain file (the name for which is in the sun_path field).

Without going into too much detail, I'll outline the steps a server program usually has to go through to do it's thing. While I'm at it, I'll be trying to implement an "echo server" which just echos back everything it gets on the socket.

Here are the server steps:

Call socket(): A call to socket() with the proper arguments creates the Unix socket:
```
    unsigned int s, s2;
    struct sockaddr_un local, remote;
    int len;

    s = socket(AF_UNIX, SOCK_STREAM, 0);
```
The second argument, SOCK_STREAM, tells socket() to create a stream socket. Yes, datagram sockets (SOCK_DGRAM) are supported in the Unix domain, but I'm only going to cover stream sockets here. For the curious, see Beej's Guide to Network Programming for a good description of unconnected datagram sockets that applies perfectly well to Unix sockets. The only thing that changes is that you're now using a struct sockaddr_un instead of a struct sockaddr_in.

One more note: all these calls return -1 on error and set the global variable errno to reflect whatever went wrong. Be sure to do you error checking.
Call bind(): You got a socket descriptor from the call to socket(), now you want to bind that to an address in the Unix domain. (That address, as I said before, is a special file on disk.)
```
    local.sun_family = AF_UNIX;  /* local is declared before socket() ^ */
    local.sun_path = "/home/beej/mysocket";
    unlink(local.sun_path);
    len = strlen(local.sun_path) + sizeof(local.sun_family);
    bind(s, (struct sockaddr *)&local, len);
```
This associates the socket descriptor "s" with the Unix socket address "/home/beej/mysocket". Notice that we called unlink() before bind() to remove the socket if it already exists. You will get an EINVAL error if the file is already there.
Call listen(): This instructs the socket to listen for incoming connections from client programs:
```
    listen(s, 5);
```
The second argument, 5, is the number of incoming connections that can be queued before you call accept(), below. If there are this many connections waiting to be accepted, additional clients will generate the error ECONNREFUSED.
Call accept(): This will accept a connection from a client. This function returns another socket descriptor! The old descriptor is still listening for new connections, but this new one is connected to the client:
```
    len = sizeof(struct sockaddr_un);
    s2 = accept(s, &remote, &len);
```
When accept() returns, the remote variable will be filled with the remote side's struct sockaddr_un, and len will be set to its length. The descriptor s2 is connected to the client, and is ready for send() and recv(), as described in the Network Programming Guide.
Handle the connection and loop back to accept(): Usually you'll want to communicate to the client here (we'll just echo back everything it sends us), close the connection, then accept() a new one.
```
    while (len = recv(s2, &buf, 100, 0), len > 0)
        send(s2, &buf, len, 0);

    /* loop back to accept() from here */
```
Close the connection: You can close the connection either by calling close(), or by calling shutdown().

With all that said, here is some source for an echoing server, echos.c. All it does is wait for a connection on a Unix socket (named, in this case, "echo_socket").

    #include <stdio.h>
    #include <stdlib.h>
    #include <errno.h>
    #include <string.h>
    #include <sys/types.h>
    #include <sys/socket.h>
    #include <sys/un.h>

    #define SOCK_PATH "echo_socket"

    int main(void)
    {
        int s, s2, t, len;
        struct sockaddr_un local, remote;
        char str[100];

        if ((s = socket(AF_UNIX, SOCK_STREAM, 0)) == -1) {
            perror("socket");
            exit(1);
        }

        local.sun_family = AF_UNIX;
        strcpy(local.sun_path, SOCK_PATH);
        unlink(local.sun_path);
        len = strlen(local.sun_path) + sizeof(local.sun_family);
        if (bind(s, (struct sockaddr *)&local, len) == -1) {
            perror("bind");
            exit(1);
        }

        if (listen(s, 5) == -1) {
            perror("listen");
            exit(1);
        }

        for(;;) {
            int done, n;
            printf("Waiting for a connection...\n");
            t = sizeof(remote);
            if ((s2 = accept(s, (struct sockaddr *)&remote, &t)) == -1) {
                perror("accept");
                exit(1);
            }

            printf("Connected.\n");

            done = 0;
            do {
                n = recv(s2, str, 100, 0);
                if (n <= 0) {
                    if (n < 0) perror("recv");
                    done = 1;
                }

                if (!done) 
                    if (send(s2, str, n, 0) < 0) {
                        perror("send");
                        done = 1;
                    }
            } while (!done);

            close(s2);
        }

        return 0;
    }

As you can see, all the aforementioned steps are included in this program: call socket(), call bind(), call listen(), call accept(), and do some network send()s and recv()s.

There needs to be a program to talk to the above server, right? Except with the client, it's a lot easier because you don't have to do any pesky listen()ing or accept()ing. Here are the steps:

Call socket() to get a Unix domain socket to communicate through.
Set up a struct sockaddr_un with the remote address (where the server is listening) and call connect() with that as an argument
Assuming no errors, you're connected to the remote side! Use send() and recv() to your heart's content!

How about code to talk to the echo server, above? No sweat, friends, here is echoc.c:

    #include <stdio.h>
    #include <stdlib.h>
    #include <errno.h>
    #include <string.h>
    #include <sys/types.h>
    #include <sys/socket.h>
    #include <sys/un.h>
    
    #define SOCK_PATH "echo_socket"

    int main(void)
    {
        int s, t, len;
        struct sockaddr_un remote;
        char str[100];

        if ((s = socket(AF_UNIX, SOCK_STREAM, 0)) == -1) {
            perror("socket");
            exit(1);
        }

        printf("Trying to connect...\n");

        remote.sun_family = AF_UNIX;
        strcpy(remote.sun_path, SOCK_PATH);
        len = strlen(remote.sun_path) + sizeof(remote.sun_family);
        if (connect(s, (struct sockaddr *)&remote, len) == -1) {
            perror("connect");
            exit(1);
        }

        printf("Connected.\n");

        while(printf("> "), fgets(str, 100, stdin), !feof(stdin)) {
            if (send(s, str, strlen(str), 0) == -1) {
                perror("send");
                exit(1);
            }

            if ((t=recv(s, str, 100, 0)) > 0) {
                str[t] = '\0';
                printf("echo> %s", str);
            } else {
                if (t < 0) perror("recv");
                else printf("Server closed connection\n");
                exit(1);
            }
        }

        close(s);

        return 0;
    }

In the client code, of course you'll notice that there are only a few system calls used to set things up: socket() and connect(). Since the client isn't going to be accept()ing any incoming connections, there's no need for it to listen(). Of course, the client still uses send() and recv() for transferring data. That about sums it up.

`socketpair()`--quick full-duplex pipes

What if you wanted a pipe(), but you wanted to use a single pipe to send and recieve data from both sides? Since pipes are unidirectional (with exceptions in SYSV), you can't do it! There is a solution, though: use a Unix domain socket, since they can handle bi-directional data.

What a pain, though! Setting up all that code with listen() and connect() and all that just to pass data both ways! But guess what! You don't have to!

That's right, there's a beauty of a system call known as socketpair() this is nice enough to return to you a pair of already connected sockets! No extra work is needed on your part; you can immediately use these socket descriptors for interprocess communication.

For instance, lets set up two processes. The first sends a char to the second, and the second changes the character to uppercase and returns it. Here is some simple code to do just that, called spair.c (with no error checking for clarity):

    #include <stdio.h>
    #include <stdlib.h>
    #include <ctype.h>
    #include <unistd.h>
    #include <sys/types.h>
    #include <sys/socket.h>

    int main(void)
    {
        int sv[2]; /* the pair of socket descriptors */
        char buf; /* for data exchange between processes */

        socketpair(AF_UNIX, SOCK_STREAM, 0, sv);

        if (!fork()) {  /* child */
            read(sv[1], &buf, 1);
            printf("child: read '%c'\n", buf);
            buf = toupper(buf);  /* make it uppercase */
            write(sv[1], &buf, 1);
            printf("child: sent '%c'\n", buf);

        } else { /* parent */
            write(sv[0], "b", 1);
            printf("parent: sent 'b'\n");
            read(sv[0], &buf, 1);
            printf("parent: read '%c'\n", buf);
        }
        return 0;
    }

Sure, it's an expensive way to change a character to uppercase, but it's the fact that you have simple communication going on here that really matters.

One more thing to notice is that socketpair() takes both a domain (AF_UNIX) and socket type (SOCK_STREAM). These can be any legal values at all, depending on which routines in the kernel you want to handle your code, and whether you want stream or datagram sockets. I chose AF_UNIX sockets because this is a Unix sockets document and they're a bit faster than AF_INET sockets, I hear.

Finally, you might be curious as to why I'm using write() and read() instead of send() and recv(). Well, in short, I was being lazy. See, by using these system calls, I don't have to enter the flags argument that send() and recv() use, and I always set it to zero anyway. Of course, socket descriptors are just file descriptors like any other, so they respond just fine to many file manipulation system calls.

Old News ;-)

Unix socket magic

Here's another technique that helps you split an application into a privileged and a non-privileged part. In the fork example, we used a pipe for communication between the front-end and the backend. One drawback with this is that pipes are one-way only, so you'd need two of them if the back end is to talk to the front-end as well. Another problem with the fork approach in general is that the two processes cannot exchange resources such as open file descriptors easily. Imagine an application where the user selects one out of several serial ports, and wants to open it. You can design the application so that the front-end asks the back-end to open the serial device, but how do you transfer the open file to the front-end process?

This is where Unix domain sockets come in. This family of sockets is for local communication only, i.e. you cannot use them across a network. They do have some properties that make them unique; one of them is what's commonly called file descriptor passing. One process can attach a set of file descriptors to a message it sends through the socket, and if the peer is willing to receive them, these open files are attached to the recipient's file set.

Here's an outline of using a back end for opening serial ports:
int     backend_fd;

void init_backend(void)
{
        char    buffer[1024];
        int     pair[2], fd, n;
        pid_t   pid;

        if (socketpair(PF_UNIX, SOCK_DGRAM, 0, pair) < 0)
                fatal("socketpair failed");
        if ((pid = fork()) < 0)
                fatal("fork failed");
        if (pid != 0) {
                if (setuid(getuid()) < 0)
                        fatal("unable to drop privs");
                backend_fd = pair[0];
                close(pair[1]);
                return;
        }

        /* We're the backend */
        close(pair[0]);
        fd = pair[1];

        while ((n = recv(fd, buffer, sizeof(buffer)-1, 0)) > 0) {
                char            control[sizeof(struct cmsg)+10];
                struct msghdr   msg;
                struct cmsghdr  *cmsg;
                struct iovec    iov;
                int             tty;

                buffer[n] = '\0';
                if (strchr(buffer, '/') != NULL
                 || strncmp(buffer, "ttyS", 4))
                        reply(fd, "bad tty path");
                else
                if ((tty = lock_and_open_port(buffer)) < 0)
                        reply(fd, "tty already locked");
                else {
                        /* Response data */
                        iov.iov_base = "OK";
                        iov.iov_len  = 2;

                        /* compose the message */
                        memset(&msg, 0, sizeof(msg));
                        msg.msg_iov = &iov;
                        msg.msg_iovlen = 1;
                        msg.msg_control = control;
                        msg.msg_controllen = sizeof(control);

                        /* attach open tty fd */
                        cmsg = CMSG_FIRSTHDR(&msg);
                        cmsg->cmsg_level = SOL_SOCKET;
                        cmsg->cmsg_type = SCM_RIGHTS;
                        cmsg->cmsg_len = CMSG_LEN(sizeof(tty));
                        *(int *)CMSG_DATA(cmsg) = tty;

                        msg.msg_controllen = cmsg->cmsg_len;

                        if (sendmsg(fd, &msg, 0) < 0)
                                fatal("sendmsg failed");
                }
        }
        exit(0);
}

int open_tty(const char *name)
{
        char            data[1024], control[1024];
        struct msghdr   msg;
        struct cmsghdr  *cmsg;
        struct iovec    iov;

        if (write(backend_fd, name, strlen(name)) < 0)
                fatal("write failed");

        memset(&msg, 0, sizeof(msg));
        iov.iov_base   = data;
        iov.iov_len    = sizeof(data)-1;
        msg.msg_iov    = &iov;
        msg.msg_iovlen = 1;
        msg.msg_control = control;
        msg.msg_controllen = sizeof(control);

        if (recvmsg(backend_fd, &msg, 0) < 0)
                fatal("recvmsg failed");

        data[iov.iov_len] = '\0';
        if (strcmp(data, "OK")) {
                printf("failed to open %s: %s\n", name, data);
                return -1;
        }

        /* Loop over all control messages */
        cmsg = CMSG_FIRSTHDR(&msg);
        while (cmsg != NULL) {
                if (cmsg->cmsg_level == SOL_SOCKET
                 && cmsg->cmsg_type  == SCM_RIGHTS)
                        return *(int *) CMSG_DATA(cmsg);
                cmsg = CMSG_NXTHDR(&msg, cmsg);
        }

        printf("failed to open %s: bug!\n");
        return -1;
}

int
main(int argc, char **argv)
{
        init_backend();

        /* parse arguments, set up GUI etc  */

        /* now open tty */
        fd = open_tty("ttyS0");
}
The init_backend function, which is called as the very first thing in main(), creates a Unix socket pair and forks a worker process that continues with root privilege, while the main parent process that does all the GUI stuff drops all privilege before returning to main().

When the frontend comes around to opening a serial port, it sends the name of the device to the backend via the Unix socket. The backend performs some sanity checks on the name to make sure this is indeed a serial port and not /etc/shadow it's about to open, and tries to create a lock file. If any of this fails, it simply returns an error message to the front-end. If all this succeeds however, it sends the string OK as response, and sends the file descriptor of the open tty along.

This code, as well as the code that receives the open tty descriptor in open_tty looks quite complicated, and it really is. The reason for this is that the only way to do file descriptor passing is by using sendmsg and recvmsg, and a control message (struct cmsghdr) attached to it. I will not go into greater details here concerning these details; if this is all greek to you (as it was to me when I first tried to understand it), refer to the manual pages for sendmsg and recvmsg, as well as cmsg(3).

There's a second control message Unix sockets offer which is quite interesting in a security context. On Linux and BSD, Unix sockets allow you to obtain the Unix credentials of the process that sent you a particular message. These credentials come along as a control message at level SOL_SOCKET, type SCM_CREDENTIALS. They're passed as a struct containing uid, gid, and pid of the sender process.

This is quite useful for applications that are supposed to serve local users only, and need to know the identity of the user connecting to them.

The most convenient way to use this feature is for the server to set the SO_PASSCRED socket option. It can then retrieve the user credentials every time the client sends a message:
int
svc_make(const char *pathname)
{
        struct sockaddr_un sun;
        int             on = 1;

        /* create server socket */
        fd = socket(PF_UNIX, SOCK_STREAM, 0);

        /* bind it */
        memset(&sun, 0, sizeof(sun));
        sun.sun_family = AF_UNIX;
        strcpy(sun.sun_path, pathname);
        bind(fd, (struct sockaddr *) &sun, sizeof(sun));
        listen(fd, 10);

        /* turn on credentials passing */
        setsockopt(fd, SOL_SOCKET, SO_PASSCRED, &on, sizeof(on));
        return fd;
}

int
svc_recv(int fd, char *buffer, size_t size, struct ucred *cred)
{
        char            control[1024];
        struct msghdr   msg;
        struct cmsghdr  *cmsg;
        struct iovec    iov;
        int             result;

        memset(&msg, 0, sizeof(msg));
        iov.iov_base = buffer;
        iov.iov_len = size;
        msg.msg_iov = &iov;
        msg.msg_iovlen = 1;
        msg.msg_control = control;
        msg.msg_controllen = sizeof(control);

        if (recvmsg(fd, &msg, 0) < 0)
                return -1;

        result = -1;
        cmsg = CMSG_FIRSTHDR(&msg);
        while (cmsg != NULL) {
                if (cmsg->cmsg_level == SOL_SOCKET
                 && cmsg->cmsg_type  == SCM_CREDENTIALS) {
                        memcpy(cred, CMSG_DATA(cmsg), sizeof(*cred));
                        result = iov.iov_len;
                } else
                if (cmsg->cmsg_level == SOL_SOCKET
                 && cmsg->cmsg_type  == SCM_RIGHTS) {
                        dispose_fds((int *) CMSG_DATA(cmsg),
                                (cmsg->cmsg_len - CMSG_LEN(0))/sizeof(int));
                }
                cmsg = CMSG_NXTHDR(&msg, cmsg);
        }

        return result;
}
The svc_make routine creates a Unix stream socket, and sets its SO_PASSCRED option. The svc_recv function receives data from the client, and in addition extracts the sender's credentials. This gives the server the uid and gid of the process that sent the message. This information is reliable (well, it's as trustworthy as the integrity of your kernel).

There are two things to watch out for, however. The first is that the identity of the sender may change from message to message. If you don't want to deal with this kind of multiple personality disorder, you should at least verify that the uid/gid of the client remains the same, and balk if not.

The second issue is that a process receiving any control messages via Unix sockets can also be sent socket descriptors by a client. If you're not prepared to handle file descriptors passed by the client, an attacker can flood your server with open file descriptors until it reaches its resource limit; after that, it will be unable to accept new connections. This is why the sample code above calls the dispose_fds function when receiving file descriptors from the client.^11.7

BSD Sockets: A Quick & Dirty Primer by Jim Frost

"The socket is the BSD method for accomplishing interprocess communication (IPC). What this means is a socket is used to allow one process to speak to another, very much like the telephone is used to allow one person to speak to another. "

``As you delve into the mysteries of UNIX, you find more and more things that are difficult to understand immediately. One of these things, at least for most people, is the BSD socket concept. This is a short tutorial that explains what they are, how they work, and gives sample code showing how to use them.'' --Jim Frost

Berkeley UNIX^® System Calls and Interprocess Communication: The purpose of this paper is to discuss interprocess communication in the context of Berkeley UNIX. Special emphasis will be given to those system calls concerned with the creation, management, and use of sockets. --Lawrence Besaw

Berkeley UNIX System Calls and Interprocess Communication

Unix Sockets

socketpair()--quick full-duplex pipes

Old News ;-)

"The socket is the BSD method for accomplishing interprocess communication (IPC). What this means is a socket is used to allow one process to speak to another, very much like the telephone is used to allow one person to speak to another. "

Recommended Links

`socketpair()`--quick full-duplex pipes