You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info

*Edge Microgateway v. 3.1.5 and later*

## Overview

The Edge Microgateway CLI lets you control and manage all aspects of an Edge Microgateway
instance.

> [!NOTE]
> **Note:**
>
> The [Setting up
> and configuring Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway) provides a good overview of the most commonly used
> commands.

## Managing certificates

The `cert` commands let you install and manage the public/private key pair
that is used to sign bearer tokens used by clients to make secure calls through Edge
Microgateway. The keys are stored on Apigee Edge in an encrypted Key Value Map (KVM). Edge Microgateway uses the
public key to validate signed bearer tokens. These keys are generated when you run the edgemicro
configure command, as explained in [Setting up and
configuring Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway). You can use the **cert** commands described here
to regenerate and manage these keys if needed.

### Install a certificate

Installs the keys in an encrypted Key Value Map (KVM) and returns the
public key as output. Key pairs are scoped to a specified organization.

**Usage**

```
edgemicro cert install -o [organization] -e [environment] -u [username] -p [password] --force
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-f, --force` | (Optional) If a key is already stored in the encrypted KVM, force its replacement. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro cert install -o docs -e test -u jdoe@example.com -f
```

**Output**

```
current nodejs version is v12.5.0
current edgemicro version is 3.0.2
password:
deleting vault
creating vault
adding private_key
adding public_key
installed cert
```

### Delete a certificate

Deletes the key pair for an organization.

**Usage**

```
edgemicro cert delete -o [organization] -e [environment] -u [username] -p [password]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro cert delete -o docs -e test -u jdoe@example.com
```

**Output**

```
deleting vault
Vault deleted!
```

### Check a certificate

Checks that your organization has a certificate installed.

**Usage**

```
edgemicro cert check -o [organization] -e [environment] -u [username] -p [password]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro cert check -o docs -e test -u jdoe@example.com
```

**Output** **(Success)**

```
checked cert successfully
```

**Output** **(Failure)**

If the certificate does not exist, an error is returned.

### Get the public key

Returns the public key for the specified organization. Does not require authentication.

**Usage**

```
edgemicro cert public-key -o [organization] -e [environment]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro cert public-key -o docs -e test
```

**Output** **(Sample)**

```
---BEGIN CERTIFICATE---

MIICpDCCAYwCCQCKpXWGum9uTjANBgkq9w0BAQsFADAUMRIwEAYDVQQDEwls
b2NhbGhvc3cNMTYxMTAyMjAxNTA2WhcNMTYxMTAzMjAxNTA2WjAUMRIwEAYD
VQQDEwlsb2Nvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDD
ETr/ne/gP47+9LgjLvBJjpbFVdaeUabZZ3wbA7sSIVnnNXWt3yPklrWSfIh+
L2+dq4k+YunsQE2+dwPdXA2x8DPGvqGcCdWPxnpZ7ix5Akbs8i/J+Ue0pXT4
jkpWbaDDftGL2tcxwP45yI+slpDYvmWRps07TFXkAPjGEHYPvCT9/v/35GkL
0h4v0S+XfpcjS5c47o7CIWlkgEM5GBosQUb17kuVR48392vGFPsnCP34iNe7
zguhiCXYg2zkOcj/N3AE4xKIhCz0QcewULy08GltWMmyjJ/30zs8P41JqoA4
RwfeEZ8RenN3rJQim1ppAAEwDQYJKoZIhvcNAQELBQADggEBAHcORIfc+ySe
2FMmqicNe6Wt5V/5zOaBMLsGQdqGOHB5cQc79sMBrk680KVhrwHXZ2nBIkVe
UEL+2qLY1VLfswBNAvcNwV9U4TwHq4eIANiD751oJK1tHmM/ujThQkwNf96o
6I7Ws+wfpGO3ppJCttRbtnATIxrwsCHN4i5lbW/tJSL7t/Zf6T1B+YSJU9AF
xuvLq22cCqyYJQdmKq2vVS55WRZdllm+mRtJrv7MLM9gfDPRxVlwrBz/eQHy
Fv+dwzxcvQjkz03RNhZUodzuD34DPJoYeK++rItsddwQ26KTahH80yYTAFzY
x9gfPf1/+qo=?

---END CERTIFICATE---
```

## Configuring Edge Microgateway for Apigee Edge Cloud

Enables Edge Microgateway to operate with an Apigee Edge Cloud instance. It wraps and performs
a sequence of commands to deploy a required authentication proxy to Edge, generate authentication
tokens, and update config files. For a complete working example, see the [Setting up and
configuring Edge Microgateway](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway).

> [!NOTE]
> **Note:**
>
> Apigee recommends that you use the configure command to configure Edge Microgateway. This
> command is the only command needed to configure Edge Microgateway. It automates commands such
> as genkeys, deploy, update config, verify config, and so on.

**Usage**

```
edgemicro configure -o [organization] -e [environment] -u [username] -p [password]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-r, --url` | (Optional) Specifies the virtual host alias for your organization:environment. See the Edge documentation to learn about virtual hosts. Default: `org-env.apigee.net` |
| `-c, --configDir` | (Optional) Specifies the path to the Edge Microgateway configuration file. By default, the configuration file is in **./config/config.yaml**. (Added v2.4.x) |
| `-x, --proxyName` | (Optional) Sets the basepath for the **edgemicro-auth** proxy. If the **edgemicro-auth** proxy is deployed under a different path from the default, **/edgemicro-auth** , this feature allows you to set the new path in Edge Microgateway. By default, the basepath is **/edgemicro-auth**. (Added v2.4.x) |
| `-t, --token` | (Optional) Lets you use an OAuth token for authentication instead of username/password. See also [Secure API calls with an OAuth2 access token](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway#Oauthtoken). For example: <br /> `edgemicro configure -o docs -e test -t <your token>` |
| `-v, --virtualHosts` | (Optional) Overrides the default virtual hosts, which are "`default,secure`". Use this option if you have virtual hosts specified for your Edge organization:environment other than these defaults. See the Edge documentation to learn about virtual hosts. |
| `-d, --debug` | (Optional) Provides debug information. |
| `-h, --help` | Output usage information. |

**Usage notes**

This command stores configuration information in
\~`/.edgemicro/org-env-config.yaml`.

**Example**

```
edgemicro configure -o docs -e test -u jdoe@example.com
```

**Output**

Upon success, the command returns a set of keys that you need to use when you start Edge
Microgateway.

```
...

The following credentials are required to start edge micro
  key: d2f0a246ad52b5d2a8b04ba65b43c76348aba586691cf6185cd7bb9fb78fe9f
  secret: 59813bc1db4a7ada182705ae40893c28a6fae680c3deb42aefbf1a4db42e372

edgemicro configuration complete!
```

## Generating keys

The `genkeys` command generates a key and secret pair used by Edge Microgateway to
authenticate itself when asynchronously posting analytics data to Apigee Edge.

**Usage**

```
edgemicro genkeys -o [organization] -e [environment] -u [username] -p [password]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-t, --token` | (Optional) Lets you use an OAuth token for authentication instead of username/password. See also [Secure API calls with an OAuth2 access token](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway#Oauthtoken). For example: <br /> `edgemicro genkeys -o docs -e test -t <your token>` |
| `-h, --help` | Output usage information. |

**Usage notes**

Upon success, the command returns three items. The first is a URL that you need to place in
the configuration file. The other two are a key pair that are required when you start an Edge
Microgateway instance.

- **bootstrap URL** : This URL points to an Apigee Edge service that enables an Edge Microgateway instance to send analytics data to Apigee Edge. You need to copy that URL into the Edge Microgateway config file: \~`/.edgemicro/org-env-config.yaml`.
- **key**: The key. This key, and the secret, are required as input to the CLI command used to start an instance of Edge Microgateway.
- **secret**: The secret.

**Example**

```
edgemicro genkeys -o docs -e test -u jdoe@example.com
```

**Output** **(Sample)**

Upon success, the command returns a set of keys that you need to use when you start Edge
Microgateway.

```
configuring host edgemicroservices-us-east-1.apigee.net for region us-east-1
Please copy the following property to the edge micro agent config
  bootstrap: https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/jdoe/environment/test

The following credentials are required to start edge micro
  key: db39324077989c75eac34c13d285772ea8e3b982b957b3f52916f3048511443f
  secret: 5bf8da39de0056f88fdd5f25a8602d22f312c1c8c870580a5fef55ac6637b7ae

finished
```

## Configuring Edge Microgateway for Apigee Edge Private Cloud

Configures Edge Microgateway to work with an Apigee Edge Private Cloud installation.

**Usage**

```
edgemicro private configure -o [organization] -e [environment] -u [username] -p [password]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-r, --runtime-url` | Specifies the runtime URL for your private cloud instance. |
| `-m, --mgmt-url` | The URL of the management server for your private cloud instance. |
| `-v, --virtualHosts` | Comma-separated list of virtual hosts for your organization:environment. Default "`default,secure`". |
| `-c, --configDir` | (Optional) Specifies the path to the Edge Microgateway configuration file. By default, the configuration file is in **./config/config.yaml**. (Added v2.4.x) |
| `-t, --token` | (Optional) Lets you use an OAuth token for authentication instead of username/password. See also [Secure API calls with an OAuth2 access token](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway#Oauthtoken). For example: <br /> `edgemicro configure -o docs -e test -t <your token>` |
| `-d, --debug` | (Optional) Provides debug information. |
| `-h, --help` | Output usage information. |

**Usage notes**

This command stores configuration information in
\~`/.edgemicro/org-env-config.yaml`.

> [!NOTE]
> **Note:**
>
> By default, the **edgemicro-auth** proxy expects to connect through a virtual
> host called **secure** . If your Private Cloud installation does not have this
> virtual host defined, you will receive a configuration error. Be sure to specify on the command
> line a **virtual_host** that exists. It is generally safe to specify a virtual
> host called **default**.

**Example**

```
edgemicro private configure -o docs -e test -u jdoe@example.com -r http://192.162.55.100:9002 -m http://192.162.55.100:8080
```

**Output**

Upon success, the command returns a set of keys that you need to use when you start Edge
Microgateway.

```
...

The following credentials are required to start edge micro
  key: d2f0a246ad52b5d2a8b04ba65b43c76348aba586691cf6185cd7bb9fb78fe9f
  secret: 59813bc1db4a7ada182705ae40893c28a6fae680c3deb42aefbf1a4db42e372

edgemicro configuration complete!
```

## Starting Edge Microgateway

Before starting Edge Microgateway, you must first run the **edgemicro configure**
(Public Cloud) or **edgemicro private configure** (Private Cloud). The configure
command returns the key and secret values that are required to start Edge Microgateway.

**Usage**

```
edgemicro start -o [organization] -e [environment] -k [public-key] -s [secret-key]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-k, --key` | The key value returned that is returned when you run the "`edgemicro configure`" command. |
| `-s, --secret` | The secret value returned that is returned when you run the "`edgemicro configure`" command. |
| `-p, --processes` | (Optional) The number of processes to start. Default: The number of cores on your system. |
| `-d, --pluginDir` | (Optional) Absolute path to the plugin directory. |
| `-r, --port` | (Optional) Overrides the port number specified in the \~`/.edgemicro/org-env-config.yaml` file. Default: 8000 |
| `-c, --cluster` | (Optional) Starts Edge Microgateway in cluster mode. **Note:** **As of v2.3.1, this option has been removed. In v2.3.1 and later versions, Edge Micro always starts in cluster mode.** |
| `-c, --configDir` | (Optional) Specifies the path to the Edge Microgateway configuration file. By default, the configuration file is in **./config/config.yaml**. (Added v2.4.x) |
| `-u, --configUrl` | (Optional) Specifies an endpoint from which Edge Microgateway will download its config file. (Added v2.5.x) |
| `-d, --debug` | (Optional) Provides debug information. |
| `-h, --help` | Output usage information. |

**Setting the port**

The `start` command lets you specify a port number to override the port specified
in the configuration file. You can also specify a port number using the `PORT`
environment variable. For example:

```
edgemicro start -o docs -e test -k abc123 -s xyz456 -p 2 --port 8002
```

or

```
export PORT=8002
edgemicro start -o org -e test -k key -s secret -p 2
```

If the port is in use, Edge Microgateway returns an error.

**About clustering**

Edge Microgateway employs the [Node.js
cluster module](https://nodejs.org/api/cluster.html) to enable clustering. Clustering allows Edge Microgateway to take
advantage of multi-core systems. For details, see this [Node.js documentation](https://nodejs.org/api/cluster.html).

> [!NOTE]
> **Note:**
>
> In v2.2.4.x and later versions, Edge Microgateway always starts in cluster mode. If you are
> using an older version, you can start the microgateway in cluster mode with the
> `--cluster` option. For example:
>
> ```
> edgemicro start -o docs -e test -k abc123 -s xyz456 --cluster
> ```

**Example**

```
edgemicro start -o docs -e test -k abc123 -s xyz456
```

#### Sample output:

```
...

current nodejs version is v12.5.0
current edgemicro version is 3.0.2
info: jwk_public_keys download from null returned 200 undefined
info: jwt_public_key download from https://docs-test.apigee.net/edgemicro-auth/publicKey returned 200 OK
info: products download from https://docs-test.apigee.net/edgemicro-auth/products returned 200 OK
info: config download from https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test returned 200 OK
PROCESS PID : 17991
```

## Managing tokens

The `token` commands let you obtain, decode, and verify signed OAuth2 access
tokens. See also [Secure API calls with an OAuth2 access token](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway#Oauthtoken).

### Decode a token

Decodes a signed, encoded bearer token into its plain-text JSON JWT (Java Web Token)
representation. A token conveys information about the Apigee Edge developer app that provided the
keys used to create the token, including application name, client_id, product list, and more.

**Usage**

```
edgemicro token decode -f [filename]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-f, --file` | The name of a file containing the JWT token to decode. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro token decode -f token.jwt
```

**Output (Sample)**

```
{ header: { typ: 'JWT', alg: 'RS256' },

  payload:
   { application_name: 'b43342ef-86f6-4666-a121-b9ac2025d217',
     client_id: 'O9ZQRZKnn1rdgcKQgsABSMdOsKS',
     scopes: [],
     api_product_list: [ 'MicroTest' ],
     iat: 1436280566,
     exp: 1436282365 },
  signature: '' }
```

### Generate a token

Generates a signed bearer token. The token allows client apps to make authenticated API calls
to Edge Microgateway. The token is an OAuth 2.0-compliant JSON Web Token (JWT). It requires as
input the Consumer Key (client id) and Consumer Secret (client secret) values from a registered
developer app on Apigee Edge. See also [Secure API calls with an OAuth2 access token](https://docs.apigee.com/api-platform/microgateway/3.1.5/setting-and-configuring-edge-microgateway#Oauthtoken).

> [!NOTE]
> You can also get a token by calling an API. For details, see [Using OAuth2 security](https://docs.apigee.com/api-platform/microgateway/3.1.5/operation-and-configuration-reference-edge-microgateway#usingapikeysecurity-usingoauth2tokensecurity)

**Usage**

```
edgemicro token get -o [org] -e [env] -i [client_id] -s [client_secret]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-1, --key` | The Client ID from the Developer App associated with your Microgateway-aware proxy. |
| `-s, --secret` | The Client Secret from the Developer app associated with your Microgateway-aware proxy. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro token get -o docs -e test -i 5UzOwAXGoOeo60aew94PPG5MAZE3aJp -s 6vahKFGS9a3qMLwz
```

**Output (Sample)**

```
{ token: 'eyJ0eXAiOiJKV1JhbGciOiJSUzI1NiJ9Glvbl9uYW1lIjoiNWNiMGY0NTV6TV3
EtOWMzOC00YmJjLWIzNzEtZGMxZTQzOGMxIiwiY2xpZW50X2lkIjoiNVV6T3dBWEdvSU9lbz
YwYWV3OTRQN0c1TUFaRTNhSnAiLCJzY2MiOltdLCJhcGlfcHJvZHVjdF9saXN0IjpbIkVkZ2
VNaWNyb1Rlc3RQcm9kdWN0Il0sImlhdCI3ODEyMzQ2MSwiZXhwIjoxNDc4MTI1MjYwfQ.Dx5
f5U7PXm8koNGmFX4N6VrxKMJnpndKgoJ5zWSJvBZ6Ccvhlpd85ipIIA5S2A5nx4obYWp_rpY
RJpIGYwyxP6Oq2j0rxnVjdCC4qyYMgthZjhKgEBVBe3s1ndP72GP2vV6PsSA9RQ2-yzsy9r0
TzhAZ3NJTxT1tS0XKqKngE-OhR3fJHVLAzdMDT0AmS9H0Z2NAJtQOuK6RTpCjG9B6Bc48AEM
sj7QSM-1LWiQ8LdY8k_BoC06qsTI7bCQGWwTuqL-ismbcx2bxovUxSemZIaoROfuF-dCZHG3
2aTP75WxBvvNgBBvPvQtPzbeSOtEaww' }
```

You can also generate a JWT using the management API:

```
curl -i -X POST "http://$ORG-$ENV.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "$CLIENT_ID": "your consumer key",
    "$CLIENT_SECRET": "your consumer secret",
    "grant_type": "client_credentials"
  }'
```

Where:

- <var translate="no">$ORG</var> is your Edge organization name (you must be an org administrator).
- <var translate="no">$ENV</var> is an environment in your org (such as "test" or "prod").
- <var translate="no">$CLIENT_ID</var> is the Consumer ID in the Developer App you created previously.
- <var translate="no">$CLIENT_SECRET</var> is the Consumer Secret in the Developer App you created previously.

### Verify a token

Verifies a signed bearer token against the public key stored on Apigee Edge for the specified
organization and environment.

**Usage**

```
edgemicro token verify -o [org] -e [env] -f [filename]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-f, --file` | The name of a file containing the JWT to verify. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro token get -o docs -e test -f token.jwt
```

**Sample output for valid token**

```
{ application_name: 'b43342ef-86f6-4666-a121-b9ac2025d217',

  client_id: 'O9ZQRZKnn1rdgcKQsAZUBkQSMdOsKS',

  scopes: [],

  api_product_list: [ 'MicroTest' ],

  iat: 1436396155,

  exp: 1436397954 }
```

**Sample output for invalid token**

```
{ [JsonWebTokenError: invalid token] name: 'JsonWebTokenError', message: 'invalid token' }
```

**Sample output for expired token**

```
{ [TokenExpiredError: jwt expired]

  name: 'TokenExpiredError',

  message: 'jwt expired',

  expiredAt: Tue Jul 07 2015 09:19:25 GMT-0600 (MDT) }
```

## Initializing a new Edge Microgateway configuration

Run this command once after you first install Edge Microgateway. Creates a new default
configuration file: \~`/.edgemicro/default.yaml`.

**Usage**

```
edgemicro init
```

**Parameters**

| Parameters | Description |
|---|---|
| `-c, --configDir` | (Optional) Specifies the path to the Edge Microgateway configuration file. By default, the configuration file is in **./config/config.yaml**. (Added v2.4.x) |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro init
```

**Output** **(Success)**

```
config initialized to /MyHome/.edgemicro/default.yaml
```

## Verifying Edge Microgateway configuration

Verifies that Edge Microgateway is properly configured.

**Usage**

```
edgemicro verify -o [organization] -e [environment] -k [public-key] -s [secret-key]
```

**Parameters**

**Example**

```
edgemicro verify -o docs -e test -k abc123 -s xyz456
```

**Output** **(Success)**

```
logging to /var/tmp/edgemicro-My-Machine.local-a0c48610-a148-11e6-8466-93f081b05988
installed plugin from analytics
installed plugin from oauth
a0c48610-a148-11e6-8466-93f081b05988 edge micro listening on port 8000
verifying analytics negative case: OK
verifying bootstrap url availability:OK
verifying jwt_public_key availability: OK
verifying products availability: OK
verifying quota with configured products: OK
verifying analytics with payload: OK
verification complete
```

## Check the microgateway cluster status

By default, Edge Microgateway starts in cluster mode. You can use this command to check the
status of the cluster.

> [!NOTE]
> **Note:**
>
> You must run this command from the same directory where you started Edge Microgateway. This
> command requires the presence of an `edgemicro.sock` file. You can check for the
> presence of this file by running: `ls -rtl`.

**Usage**

```
edgemicro status
```

**Parameters**

| Parameters | Description |
|---|---|
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro status
```

**Output** **(Success)**

```
current nodejs version is v12.5.0
current edgemicro version is 3.0.2
edgemicro is running with 8 workers
```

## Stopping the microgateway cluster

Stops the Edge Microgateway cluster.

> [!NOTE]
> **Note:**
>
> You must run this command from the same directory where you started Edge Microgateway. This
> command requires the presence of an edgemicro.sock file. You can check for the presence of this
> file by running: `ls -rtl`.

**Usage**

```
edgemicro stop
```

**Parameters**

| Parameters | Description |
|---|---|
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro stop
```

**Output** **(Success)**

```
current nodejs version is v12.5.0
current edgemicro version is 3.0.2
Stop Completed Successfully
```

## Reloading the microgateway cluster

Provides zero-downtime restart after a configuration change. Reloads the Edge Microgateway by
pulling in a new configuration.

> [!NOTE]
> **Note:**
>
> You must run this command from the same directory where you started Edge Microgateway. This
> command requires the presence of an edgemicro.sock file. You can check for the presence of this
> file by running: `ls -rtl`.

**Usage**

```
edgemicro reload -o [organization] -e [environment] -k [public-key] -s [secret-key]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-k, --key` | The key value returned that is returned when you run the "`edgemicro configure`" command. |
| `-s, --secret` | The secret value returned that is returned when you run the "`edgemicro configure`" command. |
| `-h, --help` | Output usage information. |

**Example**

```
edgemicro reload -o docs -e test -k abc123 -s xyz456
```

**Output** **(Success)**

```
...

Reload Completed Successfully
```

## Upgrading the edgemicro-auth proxy

To use [key rotation](https://docs.apigee.com/api-platform/microgateway/3.1.5/cli-reference-edge-microgateway#keyrotation), you must have an upgraded
edgemicro-auth proxy deployed in your Apigee Edge organization. (Added v2.5.x)

**Note:** If you configured your current Edge Micro instance before
version 2.5.2, you must upgrade this proxy if you want to use key rotation. You'll only need to
do this upgrade once.

**Usage**

```
edgemicro upgradeauth -o [organization] -e [environment] -u [username]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-u, --username` | Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-v, --virtualhost` | (Optional) The virtual host of the proxy. |
| `-b, --baseuri` | (Optional) The base URI for you organization on Apigee Edge. The default is the base URI for Apigee cloud deployments is api.enterprise.apigee.com. For on-premise deployments, the base URL may be different. |

**Example**

```
edgemicro upgradeauth -o docs -e test -u jdoe@example.com
```

**Output** **(Success)**

Upon success, the command returns output similar to the following:

```
Going to create revision 2 of API edgemicro-auth
Using /Users/jdoe/npm/lib/node_modules/edgemicro/node_modules/microgateway-edgeauth/apiproxy/edgemicro-auth.xml as the root file
Creating revision 2 of API edgemicro-auth
Uploading java resource micro-gateway-products-javacallout-2.0.0.jar
Uploading jsc resource generate-verify-jwt.js
Uploading jsc resource send-public-key.js
Uploading jsc resource set-jwt-variables.js
Uploading jsc resource set-response.js
Uploading node resource index.js
Uploading node resource node_modules_apigee-access.zip
Uploading node resource node_modules_base64url.zip
Uploading node resource node_modules_buffer-equal-constant-time.zip
Uploading node resource node_modules_ecdsa-sig-formatter.zip
Uploading node resource node_modules_jsrsasign.zip
Uploading node resource node_modules_jwa.zip
Uploading node resource node_modules_jws.zip
Uploading node resource node_modules_safe-buffer.zip
Uploading node resource package.json
Uploading policy Access-App-Info-2.xml
Uploading policy Access-App-Info.xml
Uploading policy AccessTokenRequest.xml
Uploading policy Add-Custom-Claims.xml
Uploading policy Create-OAuth-Request.xml
Uploading policy Create-Refresh-Request.xml
Uploading policy Extract-API-Key.xml
Uploading policy Extract-OAuth-Params.xml
Uploading policy Extract-Refresh-Params.xml
Uploading policy Get-Private-Key.xml
Uploading policy Get-Public-Key.xml
Uploading policy Get-Public-Keys.xml
Uploading policy JavaCallout.xml
Uploading policy Products-to-JSON-2.xml
Uploading policy Products-to-JSON.xml
Uploading policy Raise-Fault-Unknown-Request.xml
Uploading policy RefreshAccessToken.xml
Uploading policy Send-Public-Key.xml
Uploading policy Set-JWT-Variables.xml
Uploading policy Set-Response.xml
Uploading policy Verify-API-Key.xml
Uploading target TargetEndpoint-1
Uploading proxy default
Deploying revision 2 of edgemicro-auth to test
Deployment on test successful
edgemicro-auth proxy upgraded
```

## Key Value Map (KVM) upgrade


Use the `edgemicro upgradekvm` command to upgrade the KVM in your Apigee
organization. KVM upgrade is required if you wish to use [key rotation](https://docs.apigee.com/api-platform/microgateway/3.1.5/cli-reference-edge-microgateway#keyrotation).

> [!NOTE]
> **Note:** In version 3.1.5, the KVM upgrade feature was updated to address certain important functional issues. To use this feature, you must upgrade the **edgemicro-auth** policy to the version provided in Edge Microgateway 3.1.5 or a later release.

**Usage**


Edge for Public Cloud:

```
edgemicro upgradekvm -o [organization] -e [environment] -k [key] -s [secret]
```


Edge for Private Cloud:

```
edgemicro private upgradekvm -o [organization] -e [environment] -k [key] -s [secret] -p 'https://[hostname]/edgemicro-auth'
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | An environment for which you configured Edge Microgateway. |
| `-k, --key` | The key value returned that is returned when you run the "`edgemicro configure`" command. |
| `-s, --secret` | The secret value returned that is returned when you run the "`edgemicro configure`" command. |
| `-p, --proxyuri` | The URI for the **edgemicro_auth proxy** Edge Public Cloud: Optional. Edge Private Cloud: Required. Edge Public Cloud example: ``` -p 'https://[org]-[env].apigee.net/edgemicro-auth' ``` Edge Private Cloud example: ``` -p 'https://[hostname]/edgemicro-auth' ``` |

**Example**

```
edgemicro upgradekvm -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
```

**Output** **(Success)**

Upon success, the command returns output similar to the following:

```
current nodejs version is v12.5.0
current edgemicro version is 3.1.5
password:
Checking for certificate...
Certificate found!
---BEGIN PUBLIC KEY---
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsT6yVoT/h6pvkPlkUUtv
Hgs7MbDPcWxto7dZqJBwQ4oOQ0IJ2P4XGigc3kYUyPp5lFHg1ssP9+0onRpqn6Lq
z7N5iaTSv5YXb26bU2kSOl4hbwcljIzauAnBzQ13VaQ5SoflRxMGSZmTqZeu5jkQ
3JZ7F6k2bCar5sk1k84vd4WXcCVyngFlrMtlux5z0vOU56QYZFvvKYl/wOHNPLLB
Js54531CV1ZfhV3nDDq9Lh5D1C/oQVlm1Lc7BJoEUmKeFATmSsi50c14ScsmdtJ1
HqC/brSXCd185P6ifu2RH7IHKzNfcD4NlfAVmDScng4w5RxBan2avbmAJrokQ4b5
WQIDAQAB
---END PUBLIC KEY---
KVM update complete
```

## Key rotation

Use the `edgemicro rotatekey` command to rotate the public/private key pairs
that were used to generate the JWT tokens used for OAuth security on Edge Microgateway.

> [!NOTE]
> **Note:** In version 3.1.5, the KVM key rotation feature was updated to address certain important functional issues. To use this feature, you must upgrade the **edgemicro-auth** policy to the version provided in Edge Microgateway 3.1.5 or a later release.

To learn more, see [Rotating JWT keys](https://docs.apigee.com/api-platform/microgateway/3.1.5/operation-and-configuration-reference-edge-microgateway#rotatingjwtkeys).

**Usage**


Edge for Public Cloud:

```
edgemicro rotatekey -o [organization] -e [environment] -k [key] -s [secret]
```


Edge for Private Cloud:

```
edgemicro private rotatekey -o [organization] -e [environment] -k [key] -s [secret] -r '[hostname]/edgemicro-auth/rotateKey'
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | (Required) The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | (Required) An environment for which you configured Edge Microgateway. |
| `-k, --key` | The key value returned that is returned when you run the "`edgemicro configure`" command. |
| `-s, --secret` | The secret value returned that is returned when you run the "`edgemicro configure`" command. |
| `-p` | Path to a custom private key to be used by Apigee Edge. (Added 3.1.6) |
| `-c` | Path to a custom certificate to be used by Apigee Edge. (Added 3.1.6) |
| `-n, --nbf` | Configure the delay in minutes for a new private key to become effective. This delay allows time for microgateway instances to be refreshed with the new public key. A good practice is to set the delay to be more than the `config_change_poll_internal` configuration setting, which is 10 minutes by default. For more information, see [Configuring a "not before" delay](https://docs.apigee.com/api-platform/microgateway/3.1.5/operation-and-configuration-reference-edge-microgateway#configuring-a-not-before-delay). (Added 3.1.6) **Note:** If you use this option with versions of `edgemicro-auth` older than the version distributed with Edge Microgateway 3.1.6, the flag is ignored. |
| `-i, --kid` | (Optional) An ID used to match a specific key. Edge Microgateway uses this value to choose among a set of keys during key rotation. If this parameter is omitted (recommended), Edge Microgateway generates a timestamp-based key. For more information, see Section 4.5 of the JSON Web Key specification. |
| `-r, --rotatekeyuri` | Rotate key URI. Edge Public Cloud: Optional. Edge Private Cloud: Required. Public Cloud example: ``` -r 'https://[org]-[env].apigee.net/edgemicro-auth/rotateKey' ``` Edge Private Cloud example: ``` -r '[hostname]/edgemicro-auth/rotateKey' ``` |

**Example**

```
edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
```

**Output** **(Success)**

Upon success, the command returns output similar to the following:

```
current nodejs version is v12.5.0
current edgemicro version is 3.0.2
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!
```

After rotation, you can see in the Edge UI that new keys have been added to the microgateway
KVM.

### Example


This example uses the `-p` and `-c` flags to specify the path
to a private key/cert pair. These options let you pass a custom private key and certificate
pair.

```
edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
-p /users/home/keys.pem -c /users/home/cert.cert
```

## Forever monitoring

Use the `edgemicro forever` command to manage the [Forever](https://www.npmjs.com/package/forever)
process, a Node.js tool that automatically restarts a Node.js app in case the app goes down or has an error.
See also [Forever monitoring](https://docs.apigee.com/api-platform/microgateway/3.1.5/operation-and-configuration-reference-edge-microgateway#forevermonitoring).

**Usage**

You must set the following environment variables before you execute the `edgemicro forever` command:

- `EDGEMICRO_ORG` - The Apigee organization for which you configured Edge Microgateway.
- `EDGEMICRO_ENV` - An environment for which you configured Edge Microgateway.
- `EDGEMICRO_KEY` - The key value returned that was returned when you ran the "edgemicro configure" command.
- `EDGEMICRO_SECRET` - The secret value returned that was returned when you ran the "edgemicro configure" command.

```
edgemicro forever -f [forever_file] -a [start|stop]
```

**Parameters**

| Parameter | Description |
|---|---|
| `-f, --file` | Specifies the location of the `forever.json` file. |
| `-a, --action` | Either `start` or `stop`. The default is start. |

**Examples:**

To start Forever:

```
edgemicro forever -f ~/mydir/forever.json -a start
```

To stop Forever:

```
edgemicro forever -a stop
```

## Revoke keys

Use the `edgemicro revokekeys` command to revoke the key and secret credentials for an
Edge Microgateway configuration.

**Usage**

```
edgemicro revokekeys -o [organization] -e [environment] -u [username]
-k [key] -s [secret]
```

**Parameters**

| Parameters | Description |
|---|---|
| `-o, --org` | (Required) The Apigee organization for which you configured Edge Microgateway. |
| `-e, --env` | (Required) An environment for which you configured Edge Microgateway. |
| `-u, --username` | (Required) Your Apigee username. You must be an org administrator for the specified organization. |
| `-p, --password` | (Optional) Your password. You will be prompted if you do not provide this parameter on the command line. |
| `-k, --key` | (Required) The key to revoke. |
| `-s, --secret` | (Required) The secret to revoke. |

**Examples**

```
edgemicro revokekeys -o myorg -e test -u jdoe@apigee.com
-k 2c0064f5bd85f5573dcaffe21566fa7a2d49885cdbf8899370c8a4479285f -s 4b5d6355b874f7c46838893823e8d929dcb2e42fb9aebcb535089c9b98513
```

On success, you will see the following message:
`key 2c0064f5bd85f5573dcaffe21566fa7a2d49885cdbf8899370c8a4479285f revoked successfully`