Skip to end of metadata
Go to start of metadata
Icon

This is a draft under construction.

Asterisk 12 chan_pjsip CLI Specification

Here we are specifying what the use and output of each command should look like.

General formatting guidelines:

These are guidelines meant to help readability of the output.

  • 1 blank line before output and after output to separate the output from the prompt (output must begin and end with newlines)
  • 2 spaces before each line of output to separate the output from the left side of terminal
  • For tabulated content there should be 2 spaces between the longest lines in each column.
  • For <option> = <value> , vertically oriented lists of two column tables, the right-hand column containing values should be at least 2 spaces out from the longest option name.
  • When listing <option>'s we should use the actual option name when possible, rather than an expanded English version. As when you expand it, you'll run into situations where it is not clear to a user which configuration option that listing relates to.
  • For listings with more than one column, column names using more than a single word should have no whitespace and use camel case, (e.g. "LastRegTime") for reading clarity. 
    • An exception may be made where additional information needs to be expressed. As in "AORs/Contacts" or "Expiry(sec)". We should avoid this where possible.

The general formatting guidelines should override any discrepancies with the mock up output examples.

CLI Command Specifications

pjsip show endpoints


DESCRIPTION:

Shows a tabulated list of all endpoints, with each row displaying attributes related to an endpoint that may be commonly referenced or helpful when administering a system.
The output should be displayed as a tabulated listing of columns and rows, with each row holding information about an individual endpoint, or else additional information about the last endpoint listed.
In the mock up below, we see:
  • content relative to endpoint 6001 listed in a single line.
  • content relative to endpoint 6002 listed in multiple lines, where the two additional lines contain two contact listings in the 7999 AOR which is associated with endpoint 6002.
  • The list ends with a summary of how many Endpoints exist, and then how many are considered online or offline via Qualify responses

 

Mock Up Output

Name  AuthUsername  DevState   HintExt  AORs/Contacts                 Qualify  ActiveChannels
6001  6001          NOT_INUSE  6001     6001/sip:[email protected]:5060  35ms     
6002  6002          RINGING    6002     6002/sip:[email protected]:5060  32ms     <channel name>
                                        7999/sip:[email protected]:5060  34ms
                                        7999/sip:[email protected]:5060  35ms
2 Endpoints [Monitored: 2 online, 0 offline Unmonitored: 0 online, 0 offline]

 

COLUMNS:

We can only fit so much information here, and there is lots to choose from. This information was selected while thinking about items that you might check while troubleshooting and want to see all in one place.
  • Name - Endpoint section name
  • AuthUsername - username from associated auth  (how should we differ outbound vs inbound?)
  • DevState - Device state of Endpoint
  • HintExt - List of hint extensions that this Endpoint is mapped to
  • AORs/Contacts - List of contacts for each AOR associated with the Endpoint   (how to indicate static vs dynamic/registered?)
  • Qualify - Response time for each contact, or N/A
  • ActiveChannels - List of active channels associated to this endpoint

 

Ideas for future commands:
"pjsip show endpoints <comma-delimited list of endpoint names>"  (show specified endpoints only, rather than all endpoints, useful for systems with 100's of endpoints)

pjsip show endpoint


DESCRIPTION:

In the mock up below, you'll see:
  • Alphabetically sorted list of miscellaneous options and their current values
  • Separate sections below the misc option list for showing info related to other objects associated to the Endpoint. Such as:
    • transport
    • auth
    • aor
    • identify
  • Each separate section should contain a list of options and their related values.
  • Some sections should contain additional information, not represented as "<option> = <value>". This would primarily information that changes during run-time.
    • Examples would be:
    • Static and Registered Contacts for the associated AOR objects (static contacts shouldn't be changing, but it makes sense to display them consistently with a list of registered contacts)
    • The representation of this kind of information would really have to be determined on a case by case basis.
  • "<option> = <value>"  Is used to demonstrate where additional options and values relevant to that section would go.

Mock Up Output

Endpoint Settings
----------------
Name                    Value
------                  -------
allowsubscribe        = yes   
allowtransfer         = yes
aors                  = 6002,7999
auth                  = auth1
callerid              = Rusty Newtron <123-456-7890>
callerid_privacy      = allowed
<option>              = <value>


Associated auth Settings
--------------
AUTH: 6002

auth_type             = userpass
username              = somename
password              = 123456789
<option>              = <value>

Associated aor Settings
--------------
AOR: 6002

<option>              = <value>
Static Contacts:
  N/A
Registered Contacts:
  sip:6002:@1.2.3.4.com:5060

AOR: 7999

qualify_frequency     = 60
<option>              = <value>
Static Contacts:
  sip:[email protected]:5060
Registered Contacts:
  N/A

 

 

pjsip show registrations


DESCRIPTION:

A tabulated listing of all registrations configured in pjsip, where each row shows a single registration and various attributes about that registration.

  • Note that the list ends with a summary of how many total registrations exist, and how many are registered vs not registered.

Mock Up Output

Name      AuthUsername  Host                 Expiry(sec)  State           LastRegTime                InOut
mytrunk1  123456789     gw1.example.us:5060  3600         Registered      Wed, 18 Sep 2013 21:59:17  Outbound
mytrunk2  123456789     gw2.example.us:5060  3600         Registered      Wed, 18 Sep 2013 21:59:16  Outbound
6001      6001          192.168.0.5          3600         Not Registered                             Inbound

3 SIP registrations [2 Registered, 1 Not Registered]

COLUMNS:

  • Name - Name of the registration section
  • AuthUsername - Username from associated auth configuration
  • Host -  Host address, IP or Domain of the system we are registering to
  • Expiry(sec) -  Seconds configured for registration expiry
  • State - Registered, Registering, Not Registered
  • LastRegTime - When the last registration happened for this registration
  • InOut -  Inbound (registrations to aor objects) or Outbound (registration objects)

 

pjsip show subscriptions


DESCRIPTION:

Tabulated list showing all subscriptions, with columns displaying attributes of each subscription.

  • Note that the list ends with a summary of how many total subscriptions exist, and a distribution of types.

Mock Up Output:

Endpoint  AOR   Contact           CallID               Extension      LastState  Type      Mailbox  Expiry(sec) InOut
6001      6001  [email protected]  <Call ID goes here>  [email protected]  Idle       pidf+xml  <none>   600         Inbound
6001      6001  [email protected]  <Call ID goes here>  <none>         <none>     mwi       6001     3600        Inbound

2 active SIP subscriptions[ 1 of type "pidf+xml", 1 of type "mwi"]

COLUMNS:

  • Endpoint - What endpoint is subscribing
  • AOR - What AOR the contact is associated with
  • Contact - What contact is specifically responsible for the subscription
  • Call ID - The SIP Call ID
  • Extension - For subscription types, such as presence, this shows the associated dialplan extension.
  • LastState - For subscription types with a state, show the last state.
  • Type - The type of subscription
  • Mailbox - For MWI subscription type, the associated mailbox
  • Expiry(sec) - Subscription expiration time in seconds
  • InOut -  Inbound or Outbound

pjsip show settings


DESCRIPTION:

 List of all pjsip global and system wide settings configured. Includes ACLs since they apply to all PJSIP traffic.

 

In the mock up below, you'll see:
  • Separate sections showing settings from objects that have a "global" effect in terms of PJSIP.
    • global
    • system
    • acl
  • Each section should contain a list of options and their related values.
  • "<option> = <value>"  Is used to demonstrate where additional options and values relevant to that section would go.
  • ACL settings are displayed since they affect all PJSIP traffic.

Mock Up Ouput:

Global Settings
-----------------
maxforwards                = 70
useragent                  = Asterisk SVN-branch-12-r399268
<option> = <value>

System Settings
-----------------
timert1                    = 500
timerb                     = 3200            
compactheaders             = no      
threadpool_initial_size    = 0
threadpool_auto_increment  = 5
threadpool_idle_timeout    = 60
threadpool_max_size        = 0
<option> = <value>

Access Control List Settings
----------------------------
ACL: example_named_acl1

 0:  deny - 0.0.0.0/0.0.0.0
 1: allow - 209.16.236.0/255.255.255.255
 2: allow - 209.16.236.1/255.255.255.255

ACL: example_named_acl2

 0: allow - 0.0.0.0/0.0.0.0
 1:  deny - 10.24.20.171/255.255.255.255
 2:  deny - 10.24.20.103/255.255.255.255
 3:  deny - 209.16.236.1/255.255.255.255

  • No labels