Enable API on SMC

In order to allow inbound API connections to the SMC, you must first enable the API service on the SMC management server. To do this, open the SMC and edit the properties of the Management Server/s.

Under API Client, enable the API. If SSL connections are required, import or self sign (SMC >= 6.4) a certificate for use with the API service.

Warning

Do not check the “Use SSL for session ID” parameter when using this library. This setting is incompatible as the sessions are tracked using client sessions (for both HTTP and HTTPS)

Creating the session

In order to interact with the SMC REST API, you must first obtain a valid login session. The session is generated by authenticating an API Client and the associated authentication key.

Once the login session has been retrieved successfully, all commands or controls will reuse the same session.

When exiting, call smc.api.web.logout() to remove the active session from the Management Server.

Note

Idle API sessions will still time out after a default timeout on the Management Server.

Steps to enable API Communication on the Management Server:

  1. Enable SMC API service on the properties of the Management Server

  2. Create an API Client and obtain the ‘authentication key’

Configuring credentials

Credentials to obtain a session are obtained using the following methods (in order):

  • Provide credentials in session.login() constructor

  • In alternate specified file path (specified in login constructor)

  • In INI configured file at users ~/.smcrc

  • Environment variables

Each method is described in more detail below.

Method parameters

Example of providing the connect information through method parameters:

from smc import session

session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx')
....do stuff....
session.logout()

If a specific API version is requested, you can add the following argument to the login constructor. Otherwise the latest API version available will be used.

To find supported versions using unauthenticated call to SMC API:

>>> from smc.api.session import available_api_versions
>>> available_api_versions('http://1.1.1.1:8082')
[5.1, 6.1, 6.2]

Set up connection to specific version:

from smc import session
session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx',
              api_version='6.1')

Logging in to a specific Admin Domain:

session.login(url='http://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxx',
              domain='mydomain')

Note

If an admin domain is specified but the SMC does not have domains configured, you will be placed in the ‘Shared Domain’.

In order to use SSL connections, you must first associate a private key and certificate with the SMC API server. This is done under the Management Server properties and SMC API. Obtain the certificate for use by the client. It is recommended to ensure your certificate has the subjectAltName field set per RFC 2818.

Using SSL and specify certificate for verifying:

from smc import session
session.login(url='https://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxx',
              verify='/Users/username/home/mycacert.pem')

Using SSL to the SMC API without SSL validation (NOT recommended)

from smc import session
session.login(url='https://1.1.1.1:8082', api_key='xxxxxxxxxxxxxxxxxx',
              verify=False)

See also

smc.api.session.Session.login() for constructor arguments.

Configuration File

It is possible to store the SMC connection information in ~/.smcrc in order to simplify the login and eliminate the need to populate scripts with api key information. Syntax for ~/.smcrc:

[smc]
smc_address=1.1.1.1
smc_apikey=xxxxxxxxxxxxxxxxxxx
api_version=6.1
smc_port=8082
smc_ssl=True
verify_ssl=True
ssl_cert_file='/Users/username/home/mycacert.pem'
domain=mydomain

Then from launching scripts, you can do:

session.login()
session.logout()

Note

It is possible to override the location of .smcrc by using the ‘alt_filepath’ argument in the login constructor.

session.login(alt_filepath='/home/somedir/test')

Environment Variables

If setting environment variables, the following are supported:

SMC_ADDRESS=http://1.1.1.1:8082
SMC_API_KEY=123abc
SMC_CLIENT_CERT=path/to/cert
SMC_TIMEOUT = 30 (seconds)
SMC_API_VERSION = 6.1 (optional - uses latest by default)
SMC_DOMAIN = name of domain, Shared is default

The minimum variables that need to be present are SMC_ADDRESS and SMC_API_KEY:

export SMC_ADDRESS = http://1.1.1.1:8082
export SMC_API_KEY = foobarkey

Based on the session login constructor, you can also pass kwargs using the parameter SMC_EXTRA_ARGS.

Once the session has been successfully obtained, there is no reason to re-authenticate a new session unless logout has been called.

Note

The SMC API will automatically purge idle sessions after a configurable amount of time.

Handling retries on server busy

It is possible to override the default behavior for retrying a CRUD operation based on receiving a “Service Unavailable” (HTTP 503) response. By default, no retry is attempted. You can override this behavior and allow the API to retry an operation using a backoff algorithm.

This can be enabled through the session login constructor using the retry_on_busy boolean or after session login by calling set_retry_on_busy. If called from session login, default parameters are provided for all retry related settings. If you require more granularity, call after session login.

Note

By default, the following operation types are eligible for retry (GET/POST/PUT). You can override this by calling session.set_retry_on_busy(method_whitelist=[‘GET’, ‘POST’, ‘DELETE’])

Calling from session login:

session.login(url='https://x.x.x.x:8082', api_key='xxxxxxxxxxxxxxx',
          verify=False, timeout=30, retry_on_busy=True)

Calling after session login:

session.login()
session.set_retry_on_busy(total=5, backoff_factor=0.1)
...
session.logout()

If you are using an preferences file, place the following into your .smcrc:

[smc]
retry_on_busy=True

You can also set this on as an environment variable using the SMC_EXTRA_ARGS variable:

os.environ['SMC_EXTRA_ARGS'] = '{"retry_on_busy": "True"}'

Handling proxies

To disable the use of an intermediate proxy and force the connection to go direct, you can add the following environment variable:

os.environ['no_proxy'] = 'my.smc.at.domain'

Logging helper

To enable logging from smc-python, you can utilize the standard python logger or use convenience methods provided. These are typically called before session login:

from smc import set_file_logger
set_file_logger(log_level=10, path='/Users/foo/smc-test.log')
...

Or use a stream logger and also optionally enable urllib3 messages:

from smc import set_stream_logger
set_stream_logger(log_level=logging.DEBUG)
set_stream_logger(log_level=logging.DEBUG, logger_name='urllib3')

Another logging option is to add the following lines to your script:

import logging
logging.getLogger()
logging.basicConfig(
    level=logging.DEBUG, format='%(asctime)s %(levelname)s %(name)s.%(funcName)s: %(message)s')

The format parameter follows the standard python logging module syntax.