# Enabling netapi client interfaces

From Salt's 3006.0 release onwards, all netapi client interfaces are disabled by default.

To enable netapi/salt-api functionality, users should follow the process in this documentation. If the `netapi_enable_clients` configuration is not added to the Salt master configuration, then the netapi/salt-api will not function.

Breaking change in Salt 3006.0 and above

Users of netapi/salt-api upgrading to Salt 3006.0 must follow the process in this documentation to enable the required netapi client interfaces. If the `netapi_enable_clients` configuration is not added to the Salt master configuration netapi/salt-api will not function

## Steps to enable netapi client interfaces

1. Select client interfaces to enable

2. Update Salt master config

3. Restart salt-master and salt-api

4. Verify required functionality

### Select client interfaces to enable

Salt's client interfaces provide the ability to execute functions from execution, runner, wheel modules, and via the salt-ssh system.

It is recommended to only enable the client interfaces required to complete the tasks needed to reduce the amount of Salt functionality exposed via the netapi. For example, if the salt-ssh system is not in use, not enabling the ssh client interface will help protect the Salt master from attacks which look to exploit salt-ssh.

The main client interfaces are:

- local - run execution modules on minions

- local_subset - run execution modules on a subset of minions

- runner - run runner modules on master

- ssh - run salt-ssh commands

- wheel - run wheel modules

The local, runner, and wheel clients also have async variants to run modules asynchronously. See `netapi_enable_clients` for the complete list.

Most scenarios will require enabling the local client (and potentially its local_subset and local_async variants). The local client is equivalent to the salt command line tool and is required to run execution modules against minions.

Many deployments may also require the ability to call runner functions on the master (for example, where orchestrations are used), but the runner client should only be enabled if this is the case.

As there is not a standard netapi client application, existing users will need to assess which client interfaces are in use. Where an application or tool is making a request to a netapi module, it will usually pass an option indicating which client to use and it should be possible to inspect the source of any tools to understand which client interfaces should be enabled.

For common command line clients, such as pepper they will normally default to using the local client interface unless passed an option to specify a different client interface.

### Update Salt master config

Once it has been established which client interfaces will be required or are currently in use, those should be listed in the Salt master config, under the `netapi_enable_clients` key.

Example configuration to enable only the local client interfaces:

> netapi_enable_clients:

>   - local

>   - local_async

>   - local_batch

>   - local_subset

Example configuration to enable local client functionality and runners:

> netapi_enable_clients:

>   - local

>   - local_async

>   - local_batch

>   - local_subset

>   - runner

>   - runner_async

See `netapi_enable_clients` for the full list of available client interfaces.

### Restart salt-master and salt-api

Changes to the Salt master configuration require a restart of the salt-master service. The salt-api service should also be restarted.

### Verify required functionality

Testing that the required functionality is available can be done using curl. It is recommended to also check that client interfaces that are not required are not enabled.

Examples

Examples will have to be adjusted to set the correct username, password and external authentication values for the user's system.

Checking that the local client is enabled:

    curl -sSKi https://localhost:8000/run \
        -H 'Accept: application/x-yaml' \
        -d client='local' \
        -d tgt='*' \
        -d fun='test.ping' \
        -d username='saltdev' \
        -d password='saltdev' \
        -d eauth='auto'

    HTTP/1.1 200 OK
    Content-Type: application/x-yaml
    Server: CherryPy/18.8.0
    Date: Mon, 23 Jan 2023 14:54:58 GMT
    Allow: GET, HEAD, POST
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: GET, POST
    Access-Control-Allow-Credentials: true
    Vary: Accept-Encoding
    Content-Length: 25

    return:
      - saltdev1: true

Checking that the runner client is not enabled:

    curl -sSKi https://localhost:8000/run \
        -H 'Accept: application/x-yaml' \
        -d client='runner' \
        -d fun='test.arg' \
        -d arg='test arg' \
        -d username='saltdev' \
        -d password='saltdev' \
        -d eauth='auto'

    HTTP/1.1 400 Bad Request
    Content-Type: text/html;charset=utf-8
    Server: CherryPy/18.8.0
    Date: Mon, 23 Jan 2023 14:59:33 GMT
    Allow: GET, HEAD, POST
    Access-Control-Allow-Origin: *
    Access-Control-Expose-Headers: GET, POST
    Access-Control-Allow-Credentials: true
    Content-Length: 750
    Vary: Accept-Encoding
    ...

Further examples are available in the neatpi modules documentation.