GNU Emacs
Emacs
Dashboard

39.1 TCP Emacs server

An Emacs server usually listens to connections on a local Unix domain socket. Some operating systems, such as MS-Windows, do not support local sockets; in that case, the server uses TCP sockets instead. In some cases it is useful to have the server listen on a TCP socket even if local sockets are supported, e.g., if you need to contact the Emacs server from a remote machine. You can set server-use-tcp to non- nil to have Emacs listen on a TCP socket instead of a local socket. This is the default if your OS does not support local sockets.

If the Emacs server is set to use TCP, it will by default listen on a random port on the localhost interface. This can be changed to another interface and/or a fixed port using the variables server-host and server-port.

A TCP socket is not subject to file system permissions. To retain some control over which users can talk to an Emacs server over TCP sockets, the emacsclient program must send an authorization key to the server. This key is normally randomly generated by the Emacs server. This is the recommended mode of operation.

If needed, you can set the authorization key to a static value by setting the server-auth-key variable. The key must consist of 64 ASCII printable characters except for space (this means characters from ‘ !’ to ‘ ~’, or from decimal code 33 to 126). You can use M-x server-generate-key to get a random key.

When you start a TCP Emacs server, Emacs creates a server file containing the TCP information to be used by emacsclient to connect to the server. The variable server-auth-dir specifies the default directory containing the server file; by default, this is ~/.emacs.d/server/. In the absence of a local socket with file permissions, the permissions of this directory determine which users can have their emacsclient processes talk to the Emacs server. If server-name is an absolute file name, the server file is created where specified by that file name.

To tell emacsclient to connect to the server over TCP with a specific server file, use the ‘ -f’ or ‘ --server-file’ option, or set the EMACS_SERVER_FILE environment variable (see emacsclient Options). If server-auth-dir is set to a non-standard value, or if server-name is set to an absolute file name, emacsclient needs an absolute file name to the server file, as the default server-auth-dir is hard-coded in emacsclient to be used as the directory for resolving relative filenames.