Skip to main content

local_api

Added in v1.12.0

local_api configures the sockets that let programs on the same machine talk to a running Nebula. There are two:

  • The control socket serves the same commands as the sshd debug console, for use with nebula ctl <command>. It is on by default.
  • The info socket serves this node's identity, and the identity of the hosts it has tunnels with, over HTTP. It is off by default.

See Controlling Nebula locally with nebula ctl for how to use them.

local_api:
  control:
    enabled: true
    socket: /var/run/nebula/ctl.sock
    group: nebula
  info:
    enabled: false
    socket: /var/run/nebula/info.sock
    group: nebula-info
    socket_mode: '0660'

The sockets are only created by the nebula and nebula-service binaries. Apps that embed Nebula, such as Mobile Nebula, do not create them, and neither does nebula -test.

A problem with either socket never stops Nebula. It logs a warning, keeps forwarding traffic, and tries again on every reload, so a missing directory or a bad path can be fixed with a config edit and a reload. A reload with an unusable local_api section keeps the socket that is already running.

local_api.control.enabled​

Default: true Reloadable

Set to false to turn the control socket off. A reload that turns it off removes the socket, and one that turns it back on creates it again.

local_api.control.socket​

Default: /var/run/nebula/ctl.sock Reloadable

The path of the control socket. A reload moves the socket to a new path. nebula ctl reads this setting from the same config file to find the socket.

On Linux, macOS, and the BSDs this must be an absolute path of at most 103 bytes. On Windows it is a full named pipe name, and the default is \\.\pipe\ProtectedPrefix\Administrators\nebula-ctl.

The default path suits Nebula running as root. A Nebula running as another user, or a second Nebula on the same host, needs a path of its own. If a live socket from another Nebula is already at the path, the socket is not created and Nebula logs that the path is in use by another instance. A leftover socket from a Nebula that exited is replaced.

Socket directory​

On Linux, macOS, and the BSDs, Nebula checks the directory holding the socket before creating it, because anyone who can write that directory could replace the socket with their own:

  • If the directory is missing, Nebula creates it with mode 0755. Only the last directory is created, its parent must exist.
  • The directory must be owned by root or by the user Nebula runs as.
  • The directory must not be writable by its group or by everyone, even with the sticky bit set. A socket in /tmp is refused.

Only the directory holding the socket is checked, not the directories above it.

local_api.control.group​

Reloadable

By default, only root and the user Nebula runs as can use the control socket. On Windows, that is the account Nebula runs as, SYSTEM, and elevated members of Administrators. Other users are refused.

group names a group whose members may also use the control socket. On Linux, macOS, and the BSDs it is a group name or numeric gid, and the socket is given to that group with mode 0660. On Windows it is an account or group name, optionally domain qualified, or a SID such as S-1-5-32-545.

warning

The control socket can do everything the debug console can, including reloading the config, closing and creating tunnels, and changing the log level. Only name a group whose members you would trust with that.

On Windows the access to a pipe cannot change while it is in use. A group added on reload takes effect after a restart, and a group removed or changed on reload stops the socket until Nebula is restarted.

local_api.info.enabled​

Default: false Reloadable

Set to true to serve the info API. local_api.info.socket must also be set.

local_api.info.socket​

Required Reloadable

The path of the info socket. There is no default, because the programs that use the info API have to be told where it is anyway. The same path rules, directory checks, and Windows pipe naming apply as for the control socket, and it must be a different path from the control socket. On Windows, name the pipe under \\.\pipe\ProtectedPrefix\Administrators\, Nebula warns about a pipe outside it.

local_api.info.group​

Reloadable

A group whose members may use the info socket, named the same way as local_api.control.group. The info API is read-only and only serves certificate identity, so it is reasonable to open it to the programs that need it.

local_api.info.socket_mode​

Default: "0600", or "0660" with a group Reloadable

The file mode of the info socket on Linux, macOS, and the BSDs. It must be a quoted octal string such as "0660"; YAML reads an unquoted mode as a plain number, so one is refused. With a group set, the mode must give the group access. To let any user on the host use the info API, set this to "0666".

This setting has no effect on Windows.

There is no matching setting for the control socket, which is always 0600, or 0660 with a group.