Send Docs Feedback

CLI reference for Edge Microgateway

Edge Microgateway v. 2.0.x

Audience

This guide is for Edge Microgateway operators. It is a reference that describes all of the Edge Microgateway command-line commands in detail. Use this guide when you need more detailed information on configuration options and commands than are included in Setting up and configuring Edge Microgateway.

Getting started

If you're new to Edge Microgateway, the Setting up and configuring Edge Microgateway  is the best place to start. The setup and configuration guide covers all the steps you need to do to install, configure, start, and use an instance of Edge Microgateway.

This administrator's guide is primarily a reference. Use it to find details about Edge Microgateway features, commands, config options, logging, and plugins. 

Edge Microgateway command-line reference

The Edge Microgateway CLI lets you control and manage all aspects of an Edge Microgateway instance. The following is a comprehensive list with usage and examples for each command.

The Setting up and configuring Edge Microgateway provides a good overview of the most commonly used commands.

Command summary

  • cert commands - Install and manage a public/private key pair on Apigee Edge.
  • configure command - Performs installation and setup of Edge Microgateway in an Apigee Edge Cloud instance.
  • genkeys command - Generates public/secret key pair used by Edge Microgateway to authenticate itself when asynchronously posting analytics data to Apigee Edge.
  • private configure command - Performs installation and setup of Edge Microgateway in an Apigee Edge Private Cloud instance.
  • start command - Starts an instance of Edge Microgateway
  • token commands - Generates, decodes, and verifies signed bearer tokens that are required for clients to make authenticated API calls to Edge Microgateway.
  • verify command - Verifies that Edge Microgateway is properly configured.

Getting help on commands

The best way to learn how to use the Edge Microgateway CLI is to use the built-in help utility. For example, assuming the edgemicro executable file is in your PATH, as described in Installing Edge Microgateway:

edgemicro -h
Usage: edgemicro [options] [command]


  Commands:

    token [action]        JWT token commands, see: "edgemicro token -h"
    cert [action]         ssh cert commands to store on Apigee Vault, see: "edgemicro cert -h"
    private [action]      Automated, one-time configuration with Edge On-Premises, see: "edgemicro private -h"
    configure [options]   Automated, one-time configuration with Edge Cloud
    verify [options]      verify Edge Micro configuration by testing config endpoints
    start [options]       start the gateway based on configuration
    genkeys [options]     generate authentication keys for runtime auth between Microgateway and Edge
    help [cmd]            display help for [cmd]

  Options:

    -h, --help  output usage information

 

To get help on any command action, just use -h. For example:

edgemicro token get -h 

cert commands

The cert commands let you install and manage the public/private key pair that is used to sign bearer tokens that clients use to make secure calls through Edge Microgateway. The keys are stored on Apigee Edge in a secure vault. Edge Microgateway uses the public key to validate signed bearer tokens.

cert install

Installs the keys in a vault using the Apigee Edge secure store service and returns the public key as output. Key pairs are scoped to a specified organization.

Usage:

Usage: install [options]

  install a certificate for your organization

  Options:

    -h, --help            output usage information
    -o, --org             the organization
    -e, --env             the environment
    -u, --username        username of the organization admin
    -p, --password        password of the organization admin
    -f, --force           replace any existing keys

 

Example:

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

  org admin password: <Enter your password>

Sample output:

creating vault
adding private_key
adding public_key
Success!

Public Key:

-----BEGIN CERTIFICATE-----

<Long string of numbers and letters>

-----END CERTIFICATE-----

cert delete

Deletes the key pair for an organization.

Example:

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

   org admin password: <Enter your password>

Output:

deleting vault
Vault deleted

cert check

Checks that your organization has a certificate installed.

Example:

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

  org admin password: <Enter your password>

Output:

deleting vault
Vault deleted!

cert public-key

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

Example:

edgemicro cert public-key -o docs -e test 

Sample output:


-----BEGIN CERTIFICATE----- <Long string of numbers and letters> ​ -----END CERTIFICATE-----

configure command

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. The steps performed by this command are described step by step in Manual setup and configuration of Edge Microgateway. For a complete working example, see the Setting up and configuring Edge Microgateway.

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 [options]

Options

Usage: configure [options]

  automated, one-time setup for a new edgemicro instance

  Options:

    -h, --help                         output usage information
    -o, --org                     the organization
    -e, --env                     the environment
    -v, --virtualHosts   override virtualHosts (default: "default,secure")
    -u, --username               username of the organization admin
    -p, --password           password of the organization admin
    -r, --url                     organization's custom API URL (https://api.example.com)
    -d, --debug                        execute with debug output

Examples

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

 

genkeys command

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

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 agent config file. If you edit the default config file  (./agent/config/default.yaml) you will need to run the "edgemicro configure" command before restarting Edge Microgateway. If you edit the runtime config file (~/.edgemicro/config.yaml) you only need to restart Edge Microgateway for the change to take effect.
  • 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.

Usage:

edgemicro genkeys [options]

Options:

Usage: genkeys [options]

  generate authentication keys

  Options:

    -h, --help            output usage information
    -o, --org             the organization
    -e, --env             the environment
    -u, --username        username of the organization admin
    -p, --password        password of the organization admin

Example:

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

   org admin password: <Enter your password>

Sample output:

Please copy the following bootstrap property to your edgemicro config  

bootstrap: https://edgemicroservices.apigee.net/edgemicro/bootstrap/...

You need key and secret while starting edgemicro instance

key: <string of numbers and letters>
secret: <string of numbers and letters>

private configure command

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

Usage:

edgemicro private configure [options]

Options:

Usage: edgemicro private configure [options] 


  Options:

    -h, --help                          output usage information
    -o, --org                      the organization
    -r, --runtime-url       the URL of the runtime server
    -m, --mgmt-url             the URL of the management server
    -e, --env                      the environment
    -u, --username                username of the organization admin
    -p, --password            password of the organization admin
    -v, --virtual-hosts   comma separated virtual hosts to deploy with

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

Sample output:

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

org admin password:
delete cache config
deleted /Users/ApigeeCorporation/.edgemicro/cache-config.yaml

checking for previously deployed proxies
App  edgemicro-auth  is already deployed!
checking org for existing vault
vault already exists in your org
configuring host edgemicroservices-us-east-1.apigee.net for region us-east-1
updating agent configuration


saving configuration information to: /Users/ApigeeCorporation/.edgemicro/config.yaml

vault info:

-----BEGIN CERTIFICATE----- <Long string of numbers and letters> ​ -----END CERTIFICATE-----
The following credentials are required to start edge micro key: <string of numbers and letters> secret: <string of numbers and letters> edgemicro configuration complete!

 

start command

Starts Edge Microgateway. Before running this command, 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 [options]

Options:

Usage: start [options]

  create a client_credentials oauth token

  Options:

    -h, --help                output usage information
    -o, --org            the organization
    -e, --env            the environment
    -k, --key            key returned by the edgemicro configure command

    -s, --secret      secret returned by the edgemicro configure command
    -i, --cluster  will cluster the server
    -f, --processes <processes>             number of processes to start, defaults to # of cores

About clustering

To take best advantage of multi-core systems, you can start Edge Microgateway in cluster mode. Edge Microgateway employs the Node.js cluster module to enable this feature. For details, see the Node.js documentation

To enable cluster mode, specify the --cluster option for the edgemicro start command. Then, you can specify the number of cluster processes to start with the --processes option. For example:

edgemicro start -o docs -e test \
-k <string of numbers and letters> \
-s <string of numbers and letters> \
--cluster --processes 5

Example:

edgemicro start -o docs -e test 
-k <string of numbers and letters> 
-s <string of numbers and letters>

Sample output:

installed plugin from analytics
installed plugin from oauth
578dc8a0-f2aa-11e5-9078-47057a418de6 edge micro listening on port 8000
edge micro started

 

token commands

The token commands let you obtain, decode, and verify signed bearer tokens. By default, Edge Microgateway requires that all client requests include a valid token.

  • token get
  • token decode
  • token verify

token get

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.

Usage:

edgemicro token get [options]

Options:

Usage: get [options]

  create a client_credentials oauth token

  Options:

    -h, --help             output usage information
    -o, --org         the organization
    -e, --env         the environment
    -i, --id           the client id
    -s, --secret   the client secret

Example:

edgemicro token get -o docs -e test -i O9ZQRZKnn1NrdgKQgsAZUBkQSMdOsKS -s Wwxk3pacGTnKZLi

Sample output:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.cHBsaWbl9uYW1lIjoiYjQzMzQyZWYtODZm
Ni00NjY2LWExMjEtYjlhYkMjE3IiwiY2xpZW50X2lkIjoiTzlaUVJaS25uMU5yZGdjS1Fnc
0FaVUJrUVNNZE9zSzY29wZXMiOltdLCJhcGlfcHJvZHVjdF9saXN0IjpbIk1pY3JvVGVzdC
JdLCJiOjE0MzYzOTU3NjcsImV4cCI6NjMn0.qfiCo4prOWSMaAIH6Gvb0bRjjzHJr98dv_9b
3dELnxqXfscqQgYJsxlLL9Y3bp0FmTEg-ulODitdwgAyiaE867-DhyIEdIs3kJCMegJ1wID2
YLjaDd_6bFfC0dfED76FZUeXv0gk6GxhZTKTbOGK8EuPZb4Hnt0xK3DoD0RM1QDqJs6hvcCS
Toq45KNRUTCOxs-tYIZoEqHOUMh587qculiBsDNZ-qKiG59QNlR5krA5_dZlPez2LSV5_h_q
3O3Sa_fjvWv60sRdKNiOFxMXzCSgupSckAtM6C8bemllyOqbdNqcsoQWtgaBcF6LDA

 

Make an HTTP request to get a token

You can also make a raw HTTP request to get the token. Here's a curl example. Just substitute your org and environment names in the URL, and substitute the Consumer Id and Consumer Secret values for the client_id and client_secret params:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" -d '{"grant_type": "client_credentials", "client_id": "4t8X137pOUUtMR7wag3M1yZTcRxeK", "client_secret": "RAcOFVOvO0jns"}' -H "Content-Type: application/json"

token decode

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 get [options]

Options:

    -h, --help         output usage information
    -f, --file <file>  file containing jwt

Example:

Save a previously generated bearer token in a file.

Execute this command, where token.jwt is the file you saved:

edgemicro token decode -f token.jwt

Sample output:

{ 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: '<Long string of numbers and letters>' }

token verify

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

Usage:

edgemicro token verify [options]

Options:

Usage: verify [options]

  verify a jwt token against the public key

  Options:

    -h, --help         output usage information
    -f, --file         file containing jwt
    -o, --org          the organization
    -e, --env          the environment

Example:

edgemicro token get -o docs -e test -i O9ZQRZKnn1NrdgKQgsAZUBkQSMdOsKS -s Wwxk3pacGTnKZLi

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) }

Obtaining bearer tokens directly

You may prefer to obtain bearer tokens directly, by making an HTTP request to the token endpoint on Apigee Edge. The actual token endpoint is implemented in the proxy that is deployed with the deploy-edge-service CLI command.

Here's a curl example. Just substitute your org and environment names in the URL, and substitute the Consumer Id and Consumer Secret values obtained from a developer app on Apigee Edge for the client_id and client_secret params:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" -d '{"grant_type": "client_credentials", "client_id": "4t8X137pOUUtMR7wag3M1yZTcRxeK", "client_secret": "RAcOFVOvO0jns"}' -H "Content-Type: application/json"

Sample output:

HTTP/1.1 200 OK

X-Powered-By: Express

Cache-Control: no-store

Pragma: no-cache

Content-Type: application/json; charset=utf-8

Content-Length: 640

ETag: W/"280-ze/g/k+c9taqp110vjYQ"

Date: Fri, 17 07 2015 15:49:24 GMT

Connection: keep-alive

"<long string of numbers and letters>"

private configure command

Enables Edge Microgateway to operate with an Apigee Edge Private Cloud instance. It wraps and performs a sequence of commands to deploy required proxies to Edge, generate authentication tokens, and update config files.

The URLs you must provide are the Runtime URL (also referred to as the router IP) for your Private Cloud installation. Usually, this IP has a port 9001 or 9002, corresponding to the virtual host ports. The Management Server URL is usually an IP with an 8080 port number. If you don't know these URLs, see your Apigee Edge Administrator.  

Usage:

edgemicro private configure [options]

Options:

Usage: private configure [options]

  Automated, one-time setup of edgemicro with Apigee Private Cloud

  Options:

    -h, --help              output usage information
    -o, --org               the organization
    -r, --runtime-url       the URL of the runtime server
    -m, --mgmt-url          the URL of the management server
    -e, --env               the environment
    -u, --username          username of the organization admin
    -p, --password          password of the organization admin
    -v, --virtual-hosts     comma separated virtual hosts to deploy with

Example:

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

verify command

Verifies that Edge Microgateway is properly configured.

Usage

edgemicro verify -o <orgname> -e <envname> -k <key> -s <secret>

Options

Usage: verify [options]

  verify Edge Micro configuration by testing config endpoints

  Options:

    -h, --help        output usage information
    -o, --org         the organization
    -e, --env         the environment
    -k, --key         key returned by the edgemicro configure command
    -s, --secret      secret returned by the edgemicro configure command

Example:

edgemicro verify -o myorg -e test \
-k <string of numbers and letters> \
-s <string of numbers and letters>

Help or comments?