# IPC Connection

Client libraries connect to NSO for inter-process communication (IPC) using Unix domain sockets (Local IPC) or TCP. By default, NSO uses Local IPC over a Unix domain socket at the path `/tmp/nso/nso-ipc`, controlled by the `/ncs-config/ncs-local-ipc/path` element in `ncs.conf`. If you change the socket path, you can tell clients to use the new path through the `NCS_IPC_PATH` environment variable. Clients must also have filesystem permission to access the IPC socket path, or they will not be able to communicate with the NSO daemon process. Local IPC requires clients to run on the same host as NSO; for clients running on a remote host, use TCP IPC instead.

Alternatively, NSO can be configured to use TCP sockets for IPC by setting `/ncs-config/ncs-local-ipc/enabled` to `false` and configuring the address and port through the `/ncs-config/ncs-ipc-address/ip` (default value 127.0.0.1) and `/ncs-config/ncs-ipc-address/port` elements in `ncs.conf`. If you change these values, you will likely need to configure the clients accordingly. Note that these values have security implications; see [Security Issues](/guides/administration/installation-and-deployment/development-to-production-deployment/secure-deployment.md#securing-ipc-access). In particular, changing the address away from 127.0.0.1 may allow unauthenticated remote connections.

Many of the clients read the environment variable `NCS_IPC_PATH` to determine the Local IPC socket path, or `NCS_IPC_ADDR` and `NCS_IPC_PORT` for TCP IPC, but others might need source code changes. When both `NCS_IPC_PATH` and `NCS_IPC_PORT` are set, `NCS_IPC_PATH` takes precedence and TCP is not used. This is a list of clients that communicate with NSO and what needs to be done when the IPC configuration is changed.

<table><thead><tr><th width="218">Client</th><th>Changes required</th></tr></thead><tbody><tr><td>Remote commands via the <code>ncs</code> command</td><td>Remote commands, such as <code>ncs --reload</code>, check the environment variables <code>NCS_IPC_PATH</code> and <code>NCS_IPC_ADDR</code>/<code>NCS_IPC_PORT</code>.</td></tr><tr><td>CLI tools</td><td>The Command Line Interface (CLI) client <strong>ncs_cli</strong> and similar commands, such as <code>ncs_cmd</code> and <code>ncs_load</code>, check the environment variables <code>NCS_IPC_PATH</code> and <code>NCS_IPC_ADDR</code>/<code>NCS_IPC_PORT</code>. Alternatively, many of them also support command-line options (e.g. <code>-S</code> for socket path).</td></tr><tr><td>CDB and MAAPI clients</td><td>The address or path supplied to <code>Cdb.connect()</code> and <code>Maapi.connect()</code> must be changed.</td></tr><tr><td>Data provider API clients</td><td>The address or path supplied to <code>Dp</code> constructor socket must be changed.</td></tr><tr><td>Notification API clients</td><td>The new address or path must be supplied to the socket for the <code>Notif</code> constructor.</td></tr></tbody></table>

To run more than one instance of NSO on the same host (which can be useful in development scenarios), each instance needs its own IPC socket. Set `/ncs-config/ncs-local-ipc/path` in `ncs.conf` to different values for each instance. If, instead, you are using TCP for IPC, set `/ncs-config/ncs-ipc-address/port` in `ncs.conf` to different values. In either case, you may also need to change the NETCONF and CLI over SSH ports under `/ncs-config/netconf/transport` and `/ncs-config/cli/ssh` by either disabling them or changing their values.

## Restricting Access to the IPC Socket

By default, NSO uses Local IPC (Unix domain sockets) and relies on Unix filesystem permissions on the socket path to prevent unauthorized access. In case this is not sufficient, such as when using TCP IPC or untrusted users have shell access on the system where NSO runs, it is possible to further restrict the access to the IPC socket.

For Local IPC, you can leverage Unix filesystem permissions for the socket path to limit which OS users and groups can initiate connections to the socket. NSO may also perform additional authentication of the connecting users based on their UID; see [Authenticating IPC Access](/guides/administration/management/aaa-infrastructure.md#authenticating-ipc-access).

For TCP sockets, you can enable an access check by setting the `ncs.conf` element `/ncs-config/ncs-ipc-access-check/enabled` to `true`, and specifying a filename for `/ncs-config/ncs-ipc-access-check/filename`. The file should contain a shared secret, i.e., a random (printable ASCII) character string. Clients connecting to the IPC socket will then be required to prove that they have knowledge of the secret through a challenge handshake before they are allowed access to the NSO functions provided via the IPC socket.

{% hint style="info" %}
The access permissions on this file must be restricted via OS file permissions, such that it can only be read by the NSO daemon and client processes that are allowed to connect to the IPC socket. E.g. if both the daemon and the clients run as root, the file can be owned by root and have only "read by owner" permission (i.e. mode 0400). Another possibility is to have a group that only the daemon and the clients belong to, set the group ID of the file to that group, and have only "read by group" permission (i.e. mode 040).
{% endhint %}

To provide the secret to the client libraries and inform them that they need to use the access check handshake, you have to set the environment variable `NCS_IPC_ACCESS_FILE` to the full pathname of the file containing the secret. This is sufficient for all the clients mentioned above, i.e., there is no need to change the application code to support or enable this check.

{% hint style="info" %}
The access check must be either enabled or disabled for both the daemon and the clients. E.g., if `/ncs-config/ncs-ipc-access-check/enabled` in `ncs.conf` is not set to `true` but clients are started with the environment variable `NCS_IPC_ACCESS_FILE` pointing to a file with a secret, the client connections will fail.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nso-docs.cisco.com/guides/administration/advanced-topics/ipc-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.