Managedomain command reference

This topic describes how to run managedomain in the following modes:

  • Command interpreter mode — enter commands from a list using tab completion (default mode)
  • Interactive mode — follow instructions at the command prompt
  • Command mode — enter specific commands and parameters

The managedomain command is available in the following directory:

INSTALL_DIR/apigateway/posix/bin

For an overview of the managedomain command, see Configure an API Gateway domain.

Managedomain command interpreter mode

To run in default command interpreter mode, enter managedomain , and press Tab to view and select options. For example:

Note   You must first run initialize to register the first host in the domain in order to create and run API Gateways.

View help for a command

You can view detailed help for each command and its parameters by entering help followed by the command name. The following example shows the help for the initialize command:

Run a command

You can run a command using tab completion to specify parameters. The following example shows the available parameters for the create_instance command:

The following example creates a new API Gateway instance with a specific name and group:

Tab completion is also available for some parameter values (instance names, group names and host names). The following example shows available instances for the delete_instance command:

Managedomain interactive mode

To run in interactive mode, enter managedomain --menu, and follow the instructions at the command prompt. The following options are available:

Host management

The managedomain --menu options for host management are as follows:

Option Description Why use this option
1 Register host Add a new host that runs an API Gateway to a domain topology. This is equivalent to the initialize command. You must ensure that the host is registered in order to create and run API Gateways. For example, you can specify the following:
  • If the host is an Admin Node Manager

  • Host name

  • Node Manager name

  • Node Manager port

  • Node Manager passphrase

  • UNIX/Linux service for Node Manager

  • Trust store details

When registering a Node Manager (Admin or not) in an existing domain, you must specify host details of a running Admin Node Manager in the domain. This is not required when registering the first Admin Node Manager in a new domain because this is always an Admin Node Manager.

2 Edit a host Edit the details for a host registered in a domain topology (used occasionally). You can update the following:
  • Host name

  • Node Manager name

  • Node Manager port

  • Node Manager passphrase

  • UNIX/Linux service for Node Manager

  • Change admin capabilities

  • Enable metrics

Changing admin capabilities enables you to change a Node Manager to Admin Node Manager, or an Admin Node Manager to Node Manager. You can only change admin capabilities of the Node Manager running on the same machine. You cannot remove admin capabilities of the last Admin Node Manager in a domain, or from an Admin Node Manager that has the domain key and certificate used to sign CSRs.

When you get a license for an evaluation mode API Gateway, you must use this option to change the host from 127.0.0.1 to a network reachable address or host name. You must also restart the Node Manager to pick up any changes.

3 Delete a host Delete a registered host from a domain topology (used occasionally). You must first stop and delete all API Gateways running on the host. You can use this option to delete an Admin Node Manager or Node Manager. The Admin Node Manager that services this request is not allowed to delete itself from the domain, ensuring the domain always has at least one Admin Node Manager.
4 Change Admin Node Manager and/or credentials, currently connecting as:user admin with truststore None By default, you connect to an Node Manager using managedomain with the credentials specified at installation time. You can override these at startup by passing the --username --password command line parameters, or reset while running managedomain with this option. This username/password refers to an admin user configured in Policy Studio.

You can also use this option to select which Admin Node Manager managedomain connects to. managedomain must talk to an Admin Node Manager, which can be local or remote. By default, managedomain connects to the local running Admin Node Manager, otherwise it searches the topology and uses the first running Admin Node Manager that it finds.

API Gateway management

The managedomain --menu options for API Gateway management are as follows:

Option Description Why use this option
5 Create API Gateway instance Create a new API Gateway instance. You can also do this in Policy Studio and API Gateway Manager. You can create API Gateway instances locally or on any host configured in the topology.
6 Edit API Gateway (rename, change management port) Rename the API Gateway instance, or change the management port. This functionality is not available in Policy Studio and API Gateway Manager.
7 Delete API Gateway instance Delete an API Gateway instance from the topology, and optionally delete the files on disk. You can also do this in Policy Studio and API Gateway Manager. You must ensure that the API Gateway instance has stopped.
8 Add a tag to API Gateway Add a name-value tag to the API Gateway. The Topology view on the API Gateway Manager Dashboard displays tags and enables you to filter for API Gateway instances by tag.
9 Delete a tag from API Gateway Delete a name-value tag from the API Gateway. The tag will no longer be displayed in the API Gateway Manager Dashboard.
10 Add or remove a UNIX/Linux service for existing local API Gateway Must be run by a user with permission to create a service on the host operating system (root on UNIX/Linux). When run, adds an init.d script.

Group management

The managedomain --menu options for group management are as follows:

Option Description Why use this option
11 Edit group (rename it) Rename an API Gateway group. This functionality is not available in Policy Studio and API Gateway Manager.
12 Delete a group Delete all API Gateways in the group and the group itself. You must ensure that all API Gateways in the group have been stopped first.

Topology management

The managedomain --menu options for topology management are as follows:

Option Description Why use this option
13 Print topology Output the contents of the deployed domain topology. This includes the following:
  • Topology version

  • Hosts

  • Admin Node Managers

  • Node Managers

  • Groups

  • API Gateway instances (tags)

14 Check topologies are in sync For advanced users. Check that all Node Managers are running the same topology version. Useful only in multi-host environment. Topologies should be in sync if everything is running correctly.
15 Check the Admin Node Manager topology against another topology For advanced users. Compare the two topologies and highlights differences. There should be no differences if everything is running correctly.
16 Sync all topologies For advanced users. Forces a synchronization of all topologies.
17 Reset the local topology For advanced users. Delete the contents of the apigateway/groups directory. This means that you must re-register the host and recreate a local API Gateway instance. Alternatively, you can manually delete the contents of this directory to prevent issues if the host has been registered with other node managers.

Deployment

The managedomain --menu options for deployment are as follows:

Option Description Why use this option
18 Deploy to a group Deploy a configuration (.fed file) to API Gateways. This functionality is also available in Policy Studio and API Gateway Manager.
19 List deployment information List the deployment information for all API Gateways in a topology. This functionality is also available in Policy Studio and API Gateway Manager.
20 Create deployment archive Create a deployment archive from a directory that contains a federated API Gateway configuration.
21 Download deployment archive Download the .fed file deployed to an API Gateway. This functionality is also available in Policy Studio.
22 Update deployment archive properties Update the manifest properties relating to the deployed configuration only. This functionality is also available in Policy Studio. Enables you to update the properties without performing a new deployment.
23 Change group configuration passphrase The default passphrase for the API Gateway configuration is “”. Use this option to set a more secure password. This functionality is also available in Policy Studio.

Domain SSL certificates

The managedomain --menu options for group management are as follows:

Option Description Why use this option
24 Regenerate SSL certificates on localhost Regenerate the SSL certificates used to secure API Gateway components in the domain (for example, Node Manager and the API Gateway instances that it manages). You must restart the Node Manager on the localhost after running this option. You must run this option on all hosts in the domain.
25 Sign CSR Specify a Certificate Signing Request (CSR) to send to the Certificate Authority (CA) when applying for an SSL certificate for a Node Manager or API Gateway instance.

You can use this option when managedomain acts as the CA, and is passed the CSR to create a signed certificate. You will most likely use an external CA in production. However, this option facilitates testing of certificates signed by an external CA. You can install the API Gateway on a locked-down host, and use this feature only (no license required). You would typically only do this when using a system-generated self-signed domain certificate, and do not wish to store the domain private key on an Admin Node Manager host, and do not wish to use an external CA.

26 Submit externally signed certificate Specify an SSL certificate signed by an externally signed Certificate Authority (CA) to be used by a Node Manager or API Gateway instance. Use this option after registering a host or creating an API Gateway using a certificate signed by an external CA. Submitting the certificate with this option completes the host registration or API Gateway creation.

Managedomain command mode

You can also enter managedomain commands and parameters directly on the command line. For example, the following command creates an Admin Node Manager on the first host in the domain and signs with a user-provided domain key:

Note   You must run managedomain -i or --initialize to register the first host in the domain in order to create and run API Gateways.

For details on all available commands, enter

For detailed examples of using managedomain in command mode, see the following:

Provide credentials to managedomain

You can use the following properties file to automatically provide admin user name and password credentials to authenticate to the Admin Node Manager:

Perform the following steps:

  1. Open the managedomain.props file in an editor.
  2. Uncomment the password_exec property.
  3. Ensure that the path to ../apigateway/conf/execute.sh is correct.
  4. Change the password echoed in ../apigateway/conf/execute.sh.
  5. Save your changes to the file.
Note   You must ensure that the appropriate read and execute privileges for your operating system have been set for the execute file. You must also ensure that the execute and managedomain.props files are protected.

Alternatively, you can provide credentials on the command line. The following example shows command mode:

The following example shows interactive mode:

Related Links