Management CLI overview

jCli is Jasmin’s CLI interface, it is an advanced console to manage and configure everything needed to start messaging through Jasmin, from users to connectors and message routing management.

jCli is multi-profile configurator where it is possible to create a testing, staging and production profiles to hold different sets of configurations depending on the desired execution environment.

In order to connect to jCli and start managing Jasmin, the following requirements must be met:

  • You need a jCli admin account
  • You need to have a connection to jCli’s tcp port

Jasmin management through jCli is done using different modules (users, groups, filters, smpp connectors, http connectors ...), these are detailed in Management CLI Modules, before going to this part, you have to understand how to:

  • Configure jCli to change it’s binding host and port, authentication and logging parameters,
  • Authenticate to jCli and discover basic commands to navigate through the console,
  • Know how to persist to disk the current configuration before restarting or load a specific configuration profile to run test scenarios for example

Architecture

The Jasmin CLI interface is designed to be a user interactive interface on front of the Perspective brokers provided by Jasmin.

Jasmin CLI architecture

Jasmin CLI architecture

In the above figure, every Jasmin CLI module (blue boxes) is connected to its perspective broker, and below you find more details on the Perspective brokers used and the actions they are exposing:

  • SMPPClientManagerPB which provides the following actions:

    1. persist: Persist current configuration to disk
    2. load: Load configuration from disk
    3. is_persisted: Used to check if the current configuration is persisted or not
    4. connector_add: Add a SMPP Client connector
    5. connector_remove: Remove a SMPP Client connector
    6. connector_list: List all SMPP Client connectors
    7. connector_start: Start a SMPP Client connector
    8. connector_stop: Stop a SMPP Client connector
    9. connector_stopall: Stop all SMPP Client connectors
    10. service_status: Return a SMPP Client connector service status (running or not)
    11. session_state: Return a SMPP Client connector session state (SMPP binding status)
    12. connector_details: Get all details for a gived SMPP Client connector
    13. connector_config: Returns a SMPP Client connector configuration
    14. submit_sm: Send a submit_sm *
  • RouterPB which provides the following actions:

    1. persist: Persist current configuration to disk
    2. load: Load configuration from disk
    3. is_persisted: Used to check if the current configuration is persisted or not
    4. user_add: Add a new user
    5. user_authenticate: Authenticate username/password with the existent users *
    6. user_remove: Remove a user
    7. user_remove_all: Remove all users
    8. user_get_all: Get all users
    9. user_update_quota: Update a user quota
    10. group_add: Add a group
    11. group_remove: Remove a group
    12. group_remove_all: Remove all groups
    13. group_get_all: Get all groups
    14. mtroute_add: Add a new MT route
    15. moroute_add: Add a new MO route
    16. mtroute_remove: Remove a MT route
    17. moroute_remove: Remove a MO route
    18. mtroute_flush: Flush MT routes
    19. moroute_flush: Flush MO routes
    20. mtroute_get_all: Get all MT routes
    21. moroute_get_all: Get all MO routes
    22. mtinterceptor_add: Add a new MT interceptor
    23. mointerceptor_add: Add a new MO interceptor
    24. mtinterceptor_remove: Remove a MT interceptor
    25. mointerceptor_remove: Remove a MO interceptor
    26. mtinterceptor_flush: Flush MT interceptor
    27. mointerceptor_flush: Flush MO interceptor
    28. mtinterceptor_get_all: Get all MT interceptor
    29. mointerceptor_get_all: Get all MO interceptor

Note

(*): These actions are not exposed through jCli

Hint

SMPPClientManagerPB and RouterPB are available for third party applications to implement specific business processes, there’s a FAQ subject including an example of how an external application can use these Perspective Brokers.

Configuration

The jasmin.cfg file (INI format, located in /etc/jasmin) contains a jcli section where all JCli interface related config elements are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[jcli]
bind             = 127.0.0.1
port             = 8990
authentication   = True
admin_username   = jcliadmin
# MD5 password digest hex encoded
admin_password   = 79e9b0aa3f3e7c53e916f7ac47439bcb

log_level        = INFO
log_file         = /var/log/jasmin/jcli.log
log_format       = %(asctime)s %(levelname)-8s %(process)d %(message)s
log_date_format  = %Y-%m-%d %H:%M:%S
[jcli] configuration section
Element Default Description
bind 127.0.0.1 jCli will only bind to this specified address.
port 8990 The binding TCP port.
authentication True If set to False, anonymous user can connect to jCli and admin user account is no more needed
admin_username jcliadmin The admin username
admin_password jclipwd The admin MD5 crypted password
log_*   Python’s logging module configuration.

Warning

Don’t set authentication to False if you’re not sure about what you are doing

First connection & authentication

In order to connect to jCli, initiate a telnet session with the hostname/ip and port of jCli as set in Configuration:

telnet 127.0.0.1 8990

And depending on whether authentication is set to True or False, you may have to authenticate using the admin_username and admin_password, here’s an example of an authenticated connection:

Authentication required.

Username: jcliadmin
Password:
Welcome to Jasmin console
Type help or ? to list commands.

Session ref: 2
jcli :

Once successfully connected, you’ll get a welcome message, your session id (Session ref) and a prompt (jcli : ) where you can start typing your commands and use Management CLI Modules.

Available commands:

Using tabulation will help you discover the available commands:

jcli : [TABULATION]
persist load user group filter mointerceptor mtinterceptor morouter mtrouter smppccm httpccm quit help

Or type help and you’ll get detailed listing of the available commands with comprehensive descriptions:

jcli : help
Available commands:
===================
persist             Persist current configuration profile to disk in PROFILE
load                Load configuration PROFILE profile from disk
user                User management
group               Group management
filter              Filter management
mointerceptor       MO Interceptor management
mtinterceptor       MT Interceptor management
morouter            MO Router management
mtrouter            MT Router management
smppccm             SMPP connector management
httpccm             HTTP client connector management

Control commands:
=================
quit                Disconnect from console
help                List available commands with "help" or detailed help with "help cmd".

More detailed help for a specific command can be obtained running help cmd where cmd is the command you need help for:

jcli : help user
User management
Usage: user [options]

Options:
  -l, --list            List all users or a group users when provided with GID
  -a, --add             Add user
  -u UID, --update=UID  Update user using it's UID
  -r UID, --remove=UID  Remove user using it's UID
  -s UID, --show=UID    Show user using it's UID

Interactivity:

When running a command you may enter an interactive session, for example, adding a user with user -a will start an interactive session where you have to indicate the user parameters, the prompt will be changed from jcli : to > indicating you are in an interactive session:

jcli : user -a
Adding a new User: (ok: save, ko: exit)
> username foo
> password bar
> uid u1
> gid g1
> ok
Successfully added User [u1] to Group [g1]

In the above example, user parameters were username, password, uid and gid, note that there’s no order in entering these parameters, and you may use a simple TABULATION to get the parameters you have to enter:

...
> [TABULATION]
username password gid uid
...

Profiles and persistence

Everything done using the Jasmin console will be set in runtime memory, and it will remain there until Jasmin is stopped, that’s where persistence is needed to keep the same configuration when restarting.

Persist

Typing persist command below will persist runtime configuration to disk using the default profile set in Configuration:

jcli : persist
mtrouter configuration persisted (profile:jcli-prod)
smppcc configuration persisted (profile:jcli-prod)
group configuration persisted (profile:jcli-prod)
user configuration persisted (profile:jcli-prod)
httpcc configuration persisted (profile:jcli-prod)
mointerceptor configuration persisted (profile:jcli-prod)
filter configuration persisted (profile:jcli-prod)
mtinterceptor configuration persisted (profile:jcli-prod)
morouter configuration persisted (profile:jcli-prod)

It is possible to persist to a defined profile:

jcli : persist -p testing

Important

On Jasmin startup, jcli-prod profile is automatically loaded, any other profile can only be manually loaded through load -p AnyProfile.

Load

Like persist command, there’s a load command which will loaded a configuration profile from disk, typing load command below will load the default profil set in Configuration from disk:

jcli : load
mtrouter configuration loaded (profile:jcli-prod)
smppcc configuration loaded (profile:jcli-prod)
group configuration loaded (profile:jcli-prod)
user configuration loaded (profile:jcli-prod)
httpcc configuration loaded (profile:jcli-prod)
mointerceptor configuration loaded (profile:jcli-prod)
filter configuration loaded (profile:jcli-prod)
mtinterceptor configuration loaded (profile:jcli-prod)
morouter configuration loaded (profile:jcli-prod)

It is possible to load to a defined profile:

jcli : load -p testing

Note

When loading a profile, any defined current runtime configuration will lost and replaced by this profile configuration