What is ioxclient?

"ioxclient" is a command line tool provided as part of Cisco IOx SDK. This utility is primarily meant for assisting application development for Cisco's IOx platforms. It aims to increase developer productivity by providing easy to use CLI to perform most common operations such as :

  • App life cycle management [install, activate, deactivate, uninstall, start, stop, upgrade etc.,]
  • Application troubleshooting [view and manage application logs]
  • Life cycle management and troubleshooting for IOx services
  • Cartridge management [install, uninstall, view info, upgrade etc.,]
  • Platform management [view platform information, health, platform logs, techsupport snapshots, network information etc.,]
  • Provides a notion of profiles that captures connection information to an IOx device and switch between multiple profiles.

It interacts with the software (CAF) running in IOx platform via well defined REST APIs.

Installing ioxclient

ioxclient is typically distributed along with IOx SDK. It is also available as a stand alone, single, distributable binary for 32 and 64 bit platforms of MAC, Windows and Linux operating systems.

Please download the right version for your development machine. Once downloaded, it is advisable to mark it as executable (chmod 777) and place it somewhere it system path for easier usage.

Below is an overview of the commands supported by the tool. They will be described in more detail in the following sections.

Using ioxclient

General guidelines

  • ioxclient has commands and subcommands.
  • Each command/subcommand may require you to pass appropriate parameters
  • Some commands may also show up an interactive commandline wizard where appropriate values needs to be keyed in.
  • Each command/subcommand also has a "short name" as well. You can use the full command name or the short name. Below is an overview of top level commands. The short names are also shown:
~$ ioxclient
NAME:
   ioxclient - Command line tool to assist in app development for Cisco IOx platforms

USAGE:
   ioxclient [global options] command [command options] [arguments...]

VERSION:
   1.4.0.0

AUTHOR:
  Cisco Systems - <iox-support@cisco.com>

  COMMANDS:
    application, app Manage lifecycle of applications
    call-home, call  Set destination address for Smart License callhome
    cartridge, cr    Create/Delete/List cartridges
    debug, dbg       Set debug to on or off 
    docker, dkr      Commands for using docker tools for IOx app development
    errorcodes, err  Get ioxclient error code to description map in JSON format
    fogportal, fogp  FogPortal operations
    help, h          Shows a list of commands or help for one command
    layer, lr        Manage lifecycle of application layers
    license, lic     Execute licensing commands
    package, pkg     Package an iox application/service/cartridge. Produces an IOx compatible archive
    platform, plt    Manage IOx platform
    profiles, pr     Profile related commands
    service, svc     Manage lifecycle of services
    show, sh         Show Smart License information
    showguide, guide View ioxclient reference guide
    vm, vm		     Command for using Virtual Machine tools for IOx app development

GLOBAL OPTIONS:
  --profile            Override the profile to be used for the current command
  --non-interactive-mode   execute the command in non-interactive mode
  --help, -h           show help
  --generate-bash-completion   
  --version, -v        print the version

For instance,

$ ioxclient showguide
<-- is same as -->
$ ioxclient guide
  • Whenever the tool asks for inputs, a default value is indicated in square brackets ([]). If you are okay with the default value, just hit enter and the tool will use the value shown as the default. For example:
Your IOx platform's port number[8443] :   <= Hitting enter will cause the port to be 8443.
  • To get help, simply type:
$ ioxclient -h OR ioxclient --help
  • To get help for a specific command/subcommand :
~$ ioxclient  application
NAME:
   ioxclient application - Manage lifecycle of applications

USAGE:
   ioxclient application command [command options] [arguments...]

COMMANDS:
   list, li		List installed applications on the system
   run, r		Install, activate and start the application
   install, in		Install an application
   local_install, lin		Install an application that is already present on the target device
   start, sta		Start an installed application
   stop, stp		Stop an installed application
   restart, rs		Restart an installed application
   status, sts		Get current status of an installed application
   info, inf		Get info pertaining to an installed application
   activate, act	Activate application
   deactivate, deact	Deactivate Application
   uninstall, unin	Uninstall an installed application
   upgrade, upgr	Upgrade an application
   getconfig, getconf	Get config information of an installed application
   setconfig, setconf	Set config information for an installed application from the specified file
   logs, lgs			Manage log files
   cores, cores			Manage core files
   datamount, dm		Manage contents of application's data mount directory
   appdata, appdata		Manage files in the appdata directory under datamount
   console, con		Connect to the console of the application
   session, s		Create a new shell session in the container
   exec, ex			Execute a specific command directly in a container-based application
   metrics, met		Get resource usage metrics of installed applications
   help, h		Shows a list of commands or help for one command

OPTIONS:
   --help, -h			show help
   --generate-bash-completion


~$ ioxclient  application install
NAME:
   install - Install an application

USAGE:
   command install [command options] <application_id> <IOx package or docker image> [project dir]
  • Notation for command parameters.
  • any parameter indicated within <> is mandatory
  • any parameter indicated within [] is optional. If it is not specified, a default value is assumed. The defaults are indicated in the "help" for that command.
  • Mandatory parameter example:
~$ ioxclient  application install myapp
Insufficient Args.

NAME:
   install - Install an application

USAGE:
   command install <application_id> <archive>
  • Optional parameter example:
~$ ioxclient  platform events -h
NAME:
   events - Get platform events

USAGE:
   command events [fromseq] [toseq]. If not specified, default value is -1

Configuring ioxclient

The first time ioxclient is used, a wizard will be shown asking a few questions based on which ioxclient will configure itself. It will also create a "default" profile that captures connection information with an IOx device. Creating and using additional profiles will be described in further sections.

NOTE: The below configuration values are platform specific. Please consult the target platform's ioxclient setup section for more details provided in section Platforms.

~$ ioxclient
Config file not found :  /home/hvishwanath/.ioxclientcfg.yaml
Creating one time configuration..
Your / your organization's name : cisco
Your / your organization's URL : www.cisco.com
Your IOx platform's IP address[127.0.0.1] : 72.163.111.112
Your IOx platform's port number[8443] : 8443
Authorized user name[root] : appdev
Password for appdev :
Local repository path on IOx platform[/software/downloads]:
URL Scheme (http/https) [https]: https
API Prefix[/iox/api/v2/hosting/]:
Your IOx platform's SSH Port[2222]: 22
Activating Profile  default
  • The tool creates a default profile. Each profile has information about how to connect to a specific Cisco IOx platform.
  • The profile data is stored in $HOME/.ioxclientcfg.yaml file. Do not attempt to manually edit this file. Use ioxclient profiles commands to manipulate profile related information. Described in detail in the sections below.