Contents
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:
For an overview of the managedomain command, see Configure an API Gateway domain.
To run in default command interpreter mode, enter managedomain, and press Tab
to view and select options. For example:
C:\Oracle-11.1.2.4.0\apigateway\Win32\bin>managedomain Running in command interpreter mode. Enter 'quit' to exit. Enter 'help' to view help topics. Enter 'help topic' to view help for a topic. Press TAB to view and complete commands. > add add_service_only add_tag change_domain_passphrase change_passphrase create_archive create_instance delete_group delete_host delete_instance delete_tag deploy download_archive edit_group edit_host edit_instance help initialize list_deployments print_topology quit regen_certs remove_service reset sign_csr submit_cert topology_check topology_compare topology_merge topology_synch >
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 change_passphrase
command:
> help change_passphrase
*** Command Description ***
Change group configuration passphrase.
*** Usage ***
change_passphrase old_passphrase "" new_passphrase "12345"
*** Command Parameters ***
group : name of API Gateway's group. Required.
old_passphrase : the old passphrase.
new_passphrase : the new passphrase.
anm_host : host name for Admin Node Manager that managedomain connects to in order to execute
commands. This must be specified for the --add command, otherwise a default Admin Node
Manager will be automatically discovered if none is specified. Note that managedomain may
connect to a remote or local Admin Node Manager in order to execute commands.
anm_port : port of Admin Node Manager that managedomain connects to in order to execute
commands. Defaults to 8090.
username : username for authenticating to Admin Node Manager. Defaults to 'admin'.
password : password for authenticating to Admin Node Manager.
truststore_file : the filename for the truststore which holds all trusted Admin Node Manager
SSL certs. Default to trusting all.
truststore_password : the truststore file password which holds all trusted Admin Node Manager
SSL certs.
debug : enable debugging.
You can run a command using tab completion to specify parameters. The following example shows the
available parameters for the create_instance command:
> create_instance <press TAB> name group host instance_management_port instance_services_port passphrase sign_with_generated sign_with_user_provided sign_with_external_ca domain_passphrase sign_alg ca key_passphrase add_service service_user debug anm_host anm_port username password truststore_file truststore_password
The following example creates a new API Gateway instance with a specific name and group:
> create_instance name APIServer1 group Group1 Requesting CSR from Admin Node Manager... CSR received from Admin Node Manager. Requesting signed certificate from Admin Node Manager... Signed certificate received from Admin Node Manager. Requesting Admin Node Manager to create new API Gateway... New API Gateway SSL certificate details: dname: CN=instance-1,OU=group-2,DC=host-1 expires: Fri Apr 27 16:36:37 BST 2114 thumbprint: E6:C5:B5:6D:52:1D:74:3E:CD:3E:8B:B5:82:24:3A:78:1B:C9:27:F9 issuer dname: CN=Domain issuer thumbprint: B5:68:73:7A:7B:ED:6D:B0:04:40:CF:E3:BC:36:6D:84:F7:49:29:12 The new API Gateway 'APIServer1' in group 'Group1' has been successfully created and installed Start the new API Gateway by executing the following command: C:\Oracle-11.1.2.4.0\apigateway\Win32\bin\startinstance -g "Group1 " -n "APIServer1" You can alternatively add C:\Oracle-11.1.2.4.0\apigateway\Win32\bin\ to your path and use "startinstance -g "Group1" -n "APIServer1"". You can test the connection by visiting the URL: http://roadrunner:8080/healthcheck
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:
> delete_instance name <press TAB> APIServer1 APIServer2 > delete_instance name APIServer
To run in interactive mode, enter managedomain --menu, and follow the
instructions at the command prompt. The following options are available:
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. You must ensure
that the host is registered in order to create and run API Gateways. For example,
you can specify the following:
|
2
|
Edit a host
|
Edit the details for a host registered in a domain topology (used occasionally).
You can update the following:
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 |
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 |
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 Windows/UNIX 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 Linux, or Administrator on Windows). When run on Linux,
adds an init.d script.
|
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. |
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:
|
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.
|
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.
|
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 |
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. |
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:
managedomain -i --sign_with_user_provided --ca=/home/keys/test.p12
For more details and examples of using managedomain in command mode, see the
following:
