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[jcli]
 2bind             = 127.0.0.1
 3port             = 8990
 4authentication   = True
 5admin_username   = jcliadmin
 6# MD5 password digest hex encoded
 7admin_password   = 79e9b0aa3f3e7c53e916f7ac47439bcb
 8
 9log_level        = INFO
10log_file         = /var/log/jasmin/jcli.log
11log_format       = %(asctime)s %(levelname)-8s %(process)d %(message)s
12log_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