Overview
As of edgeCore v3.8.5, the distribution includes a command-line interface, which will ultimately replace some of the functionality of the edge.bat/edge.sh script file. The commands to be replaced will have a deprecation warning until edgeSuite v4.0, at which point they will be completely replaced. To access the new Edge CLI features (prior to version 4.0), use
es-cli.sh.
Running Edge CLI
With the exception of the help command, the edgeCore server must be running for the new Edge CLI commands to work. All Edge CLI commands must be in the following format:
es-cli.(sh|bat) [credentials] command [arguments]
where credentials can be:
-
--user username [--pass password] -
--apikey key
When passing credentials as arguments, their location in the list of arguments is not important (e.g. command[arguments] can come before the credentials). Order is only important for the command and command arguments themselves, as the command must come before the arguments for Edge CLI to properly consume them.
On Windows before v3.11.1, es-cli.bat does not exist to wrap CLI commands. As such, the .jar file must be called directly. If necessary, manually create the cli.properties file, and run the following command:
java -Dedge.cli.config=path/to/cli.properties -jar bin/cli/edge-cli-3.8.5.jar --user username [--pass password] command [arguments]
Example: C:\opt\edgeSuite-3.8.5-GA\bin>java -Dedge.cli.config="C:\opt\edgeSuite-3.8.5-GA\bin\cli\cli.properties" -jar "C:\opt\edgeSuite-3.8.5-GA\bin\cli\edge-cli-3.8.5.jar" --user admin --pass admin sysinfo
If [--pass password] is not provided, the application will provide a masked password prompt for entry.
Pre-authenticated Access
- From the same host
If accessing the CLI from the same host running edgeCore and the edgeCore instance has designated a user for CLI access, the username and password arguments can be omitted:bin/es-cli.sh command [arguments] - From any host
The API key can be specified in thecli.properties(orcustom.propertiesorlocal.propertiesfor the local instance) usingedge.cli.apikey. If this property is set, authentication can be left off and the API key will be used for all CLI operations requiring authentication.
edge.cli.apikey=dHBuaDQwLTVnNWh1NDdzMDdhc3x0Omwtc1hmPnEtXT1aOSx5TlAoNSc1dylu
Supported Commands
| Command/Alias | Args | Description | Role Required |
|---|---|---|---|
| action | -n NAME [-v VARS…] | Invoke a server action, passing in optional node variables. -n NAME: Required. The name of an existing server action in the edgeCore pipeline. -v VARS: Optional. If set, provide one or more “varName=varValue” entries to set the node variables for the action invocation. e.g. -v “foo=bar” “code=1337” | none |
| backup, bak | [–listpages] [-f FILENAME] [-p PAGES] [-l] [-c] | Creates a backup with the given filename (full backup by default). Will overwrite backups of the same name. Running –listpages will return a list of all archivable content pages. -f FILENAME is optional. The extension (.zip or .esb) will be appended to the name and does not need to be included. The default filename is “edgeSuite-export-” followed by a timestamp. Adding the -l arg will add the logs to the backup. Use -p PAGES (where PAGES is a comma-separated list of content pages) to create a partial backup. Note that the server will prepend “/Content Menu/” to all paths, so it is assumed that all folders and pages fall under the Content Menu. Example: Assume the menu structure is as follows: |
admin |
| cluster, clu | -j | -l | -s | -i [-a ALIAS] [-u URL] | Joins or leaves the cluster (must already have shared auth database and configured admin node). A command should be run from an intended content node. -j | -l | -s | -i: Join or leave or cluster status or cluster-id respectively. Must specify exactly one of these options. Status lists information about all nodes in the cluster. ID returns this node’s ID as it relates to the cluster. -a ALIAS: Alias for this content node. Required to join or leave. -u URL: URL for this content node. Used with join option. If specified, overrides default URL (http://localhost:8080, or the URL specified by the property edge.cli.url). |
admin |
| config | [–rm] -s SCOPE -k KEY [-v VALUE] | View or change config values. –rm: Optional. Removes the specified config entry. -s SCOPE: Required. Can be “global” or “group:DOMAIN_NAME”. -k KEY: Required. The configuration key, e.g. pipeline.safeSubstitution. -v VALUE: Optional. If included, the value is set for the given key, e.g. true. Otherwise, the current value (if any) will be returned. | admin |
| edit | -s SCOPE -n NAME [-e ENDPOINT] p PROPERTY [-v VALUE] | Change a connection endpoint, dataset, or account adapter property value. In the context of this command, a dataset is any feed or transform that exists in the edgeCore pipeline. -s SCOPE: Required. Can be “connection”, “dataset”, or “accountAdapter”. -n NAME: Required. Name of the connection, dataset, or accountAdapter to edit. -e ENDPOINT: Required for “connection” scope. Name of the endpoint on the connection to edit. For connections that support failover, endpoint names can be customized. The default name for the main endpoint is “Endpoint1”. Connections that do not support failover (e.g. Server Filesystem) have one endpoint and its name is “Primary”. -p PROPERTY: Required. The name of the property to edit, e.g. verboselogging. If PROPERTY is set to “*” (including the quotes so as not to be confused with the asterisk wildcard), and the VALUE argument is omitted, the server will return a list of all visible properties of the entity in question. -v VALUE: Optional. If included, the command will set the property to the value. Otherwise, the command will return the current value. | admin |
| fetch | -p PRODUCER [-v VARS…] | Fetch the data set of a producer (feed or transform), passing in optional node variables. -p PRODUCER: Required. The name of an existing producer in the edgeCore pipeline. -v VARS: Optional. If set, provide one or more “varName=varValue” entries to set the node variables for the fetch operation. e.g. -v “foo=bar” “code=1337” | none |
| health, pm | Retrieves a snapshot of the system’s performance metrics (memory and CPU usage), as well as last reboot time. | admin | |
| help, h | [command] | Lists info about commands. If the command name is supplied, lists info for the specified command. | none |
| license, lic | [-f FILENAME] | Echoes edgeCore server’s licensing information. If -f FILENAME is included, the server will load the indicated file. FILENAME should point to a license file on the same host as the Edge CLI application. | admin |
| push | [–clear] [-f FILENAME] [-d STRING] FEED | Send text-based data to a feed created from a Push Connection. The data can be read from a file (see -f FILENAME), as a string literal (see -d STRING), or via standard input (using |, <, or manual entry terminated by Ctrl+D). –clear: Optional. Excludes any data specified by file, string, or standard input. Removes existing data from the specified FEED. -f FILENAME: Optional. If specified, FILENAME must point to a readable file. -d STRING: Optional. If STRING contains spaces, it must be wrapped in double-quotes. FEED: Required. Must refer to an existing feed-in edgeCore. Note: If redirecting data to standard input (using | or <), entering one’s password via a masked password prompt as mentioned above in “Running Edge CLI” will not be an option. This is due to the fact that redirecting the input starts the JVM in non-interactive mode, which disables the console that is necessary for the password prompt. | admin |
| restore, res | [–list OPTION] [-r] [-l OPTION] [-t TYPE] [-p PROFILE] [-c] -f FILENAME | Restores the archive specified by -f FILENAME. Note that FILENAME can refer to a named archive on the target edgeCore instance (i.e. any archive name listed when running the restore command with –list archives) or it can be a path to a file anywhere on the same system as the target edgeCore instance. FILENAME is required unless running the restore command with –list OPTION. Full (.zip) restore options: -r: Removes files from the custom folders before restore -l OPTION: OPTION must be true or false. If false, the restore will preserve the current license. By default, full archives will replace the current license with the license from the archive. -t TYPE: Restore type: ALL or CONTENT_ONLY (default is ALL). A CONTENT_ONLY restore will leave existing users and groups unaffected. Partial (.esb) restore options: -p PROFILE: Restore profile name. Other options: –list OPTION: Lists all available archives or restore profiles. OPTION should be set to ‘archives’ or ‘profiles’ accordingly. -c: Coerce — required if trying to restore an archive on a non-admin server within a cluster. | admin |
| sysinfo, si | Retrieves the edgeCore version, Tomcat server version, the server’s endpoints, and shutdown port, the install home, Java version, OS, and system time zone. | none | |
| version, v | Retrieves version info for edgeCore server as well as any installed modules. If the server is part of a cluster, will also return the configuration version of all edgeCore instances in the cluster. | admin |
Configuration Settings
Edge CLI by default will target an edgeCore instance running at http://localhost:8080, with connection timeout settings (in seconds) shown below. These settings can be overridden via a properties file.
| Property Key | Property Default Value | Description |
|---|---|---|
edge.cli.url |
http://localhost:8080 | The default value for –url option. |
edge.cli.connect.timeout |
5 | TCP connect timeout for HTTP connection. |
edge.cli.connect.request.timeout |
15 | Internal connection request timeout. |
edge.cli.socket.timeout |
120 | TCP socket timeout. An activity timeout for the socket – once a connection has been established this is how much time can elapse between response packets from the server and the connection be maintained. |
ssl.permissive |
true | Trust all SSL certificates. Set this false for better security – you may then need to configure the trust store. |
If running Edge CLI on Mac or Linux, es-cli.sh will automatically set the JVM argument -Dedge.cli.config=${Install_Home}/bin/cli/cli.properties when passing commands to the Edge CLI .jar file.
If running Edge CLI on Windows, edge.cli.config must be explicitly set by the user as shown in the example above.
The URL setting also has a command-line override option (which will override both the default and the properties file settings). To activate this, run es-cli.sh with the option --url HOST, where HOST refers to the preferred target edgeCore server.
Configuring Pre-authenticated Access
If running Edge CLI and edgeCore together on the same host, the edgeCore server can be configured to allow CLI requests to pass through without requiring a username and password. To do this, a user must be designated ${Install_Home}/conf/custom.properties to act like the CLI user. This setting looks like:
edge.cli.local.user=someUser@someDomainNote: authentication without credentials is not supported when running Edge CLI from a remote host.
Exit Codes
Upon exiting, Edge CLI will return one of the following exit codes. The values and their meanings are loosely based on the BSD exit codes.
| Exit Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General Error |
| 64 | Command usage error (usually illegal arguments) |
| 69 | Service unavailable (this can result from errors with either the requests or the responses). |
| 74 | Input/output errors (general I/O errors, JSON reading/mapping errors). |
| 77 | Permission denied (usually an authentication failure) |
| 127 | Unknown Command |
Standalone CLI
It is also possible to remotely deploy and use the CLI to run commands without direct access to the full edgeCore instance. This is available with the Standalone CLI. The Standalone CLI is currently supported on Unix and Mac systems. The Standalone CLI installation files can be downloaded from this link.
Standalone CLI Setup
Once the CLI package is downloaded and unpacked, it can be used by navigating inside the /StandaloneCLI/bin directory. From there you can run CLI commands on the remote and local machine by running a command in this format: ./es-cli.sh command --user admin --pass admin --url http://instanceUrl/
Example of Standalone CLI Usage on Remote edgeCore Instance
Uploading files can be done either via cURL or SCP. In the example, we will run cURL. Information about setting up cURL or activating it can be found here on this link.
Once you set up cURL, you must run a cURL login command, which has this format:
curl -i -X POST -d j_username=youredgeadmin -d j_password=youredgeadminpass -c cookie.txtExample:
curl -i -X POST -d j_username=admin -d j_password=admin -c cookie.txthttp://13.58.167.103:8080/j_spring_security_check
Once the login is completed, you can run upload (POST) commands on a specific file or backup you want to be delivered to the remote machine:
curl -b cookie.txt -F file=@/pathtoFileonLocalMachine/Backup.ziphttp://RemoteInstanceAndPort/upload/backup/
Example:
curl -b cookie.txt -F file=@/Users/Joe/TestNew.ziphttp://13.58.167.103:8080/upload/backup/
Once the file is uploaded, it will be on your remote instance in [Install_Home]/exports. Then you can proceed with running a restore command:
./es-cli.sh restore -f /home/ubuntu/edgeSuite/exports/TestNew.zip -t CONTENT_ONLY --user admin --pass admin --urlThe backup process is almost the same but in reverse. First, you will run the backup command to create a backup in the exports directory:
./es-cli.sh backup --list --user admin --pass admin --urlAfter that you can run the curl command to retrieve the backup or any other file to your machine:
curl -b cookie.txt -o FileName.ziphttp://instanceandPort/download/archive/BackupName.zip
Example:
curl -b cookie.txt -o TestDownload.ziphttp://13.58.167.103:8080/download/archive/edgeSuite-export-20191226-152459.706.zip