utils: add helper to interact with janus admin API

[lionelnicolas]

Useful for live-enable/disable locks and refcount debugging on production, or start a PCAP dump, when the admin API is not easily accessible (e.g. janus running in a kubernetes pod). Using this you can simply:

kubectl exec your-janus-pod -- janus-admin-cli -r set_log_level -o level=5

See https://janus.conf.meetecho.com/docs/admin.html for more commands.

Janus admin connection can be configure using parameters or env vars (JANUS_HOST, JANUS_ADMIN_PORT, JANUS_ADMIN_SECRET, JANUS_ADMIN_ENDPOINT )

Examples:

#~ janus-admin-cli -r ping
{
  "janus": "pong",
  "transaction": "aNexVTIgcYbc"
}

#~ janus-admin-cli -r list_sessions
{
  "janus": "success",
  "transaction": "GgaL0xmUbBI4",
  "sessions": [
    3236169122271256,
    295460503767564,
    5854530659370442,
    5714856303331417,
    4512308604273274,
    3642487421981464,
    8938575577523615
  ]
}

#~ janus-admin-cli -r list_handles -o session_id=3236169122271256
{
  "janus": "success",
  "session_id": 3236169122271256,
  "transaction": "rR4lYK1hZTuB",
  "handles": [
    8548304105222430
  ]
}

#~ janus-admin-cli -r handle_info -o session_id=3236169122271256 -o handle_id=8548304105222430
{
  "janus": "success",
  "session_id": 3236169122271256,
  "transaction": "nXEemi7vqYzP",
  "handle_id": 8548304105222430,
  "info": {
    "session_id": 3236169122271256,
    "session_last_activity": 491266556101,
    "session_timeout": 300,
    "session_transport": "janus.transport.websockets",
    "handle_id": 8548304105222430,
    "opaque_id": "videoroom-2bjwk899v3jwrcleiqhq",
    "loop-running": true,
    "created": 426360304549,
    "current_time": 491278863887,
    "plugin": "janus.plugin.videoroom",
    "plugin_specific": {
      "hangingup": 0,
      "destroyed": 0
    },
    "flags": {
      "got-offer": false,
      "got-answer": false,
      "negotiated": false,
      "processing-offer": false,
      "starting": false,
      "ice-restart": false,
      "ready": false,
      "stopped": false,
      "alert": false,
      "trickle": false,
      "all-trickles": false,
      "resend-trickles": false,
      "trickle-synced": false,
      "data-channels": false,
      "has-audio": false,
      "has-video": false,
      "new-datachan-sdp": false,
      "rfc4588-rtx": false,
      "cleaning": false,
      "e2ee": false
    },
    "sdps": {},
    "queued-packets": 0,
    "streams": []
  }
}

#~ janus-admin-cli -r start_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430 -o folder=/tmp
{
  "janus": "success",
  "transaction": "ZPPhyQqNfLwp"
}

#~ janus-admin-cli -r stop_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430
{
  "janus": "success",
  "transaction": "mm74LKsRVaKW"
}

#~ janus-admin-cli -r set_log_level -o level=5
{
  "janus": "success",
  "transaction": "D1sGjlV3KLnm",
  "level": 5
}

#~ janus-admin-cli -r set_log_timestamps -o timestamps=true
{
  "janus": "success",
  "transaction": "hpSA0VgL8HxQ",
  "log_timestamps": true
}

#~ janus-admin-cli -r set_locking_debug -o debug=true
{
  "janus": "success",
  "transaction": "wt15AgETbPrn",
  "locking_debug": true
}

[lionelnicolas]

I created a utils/ directory to put this script. Let me know if you want me to rename this directory.

[lminiero]

This looks like a useful tool (some time ago I wrote a similar one in nodejs), but I'm not sure it belongs here. Maybe it could be its own separate repo?

[alexamirante]

This looks like a useful tool (some time ago I wrote a similar one in nodejs), but I'm not sure it belongs here. Maybe it could be its own separate repo?

Why so? It's a shell script, it won't hurt to have it here (I think it's quite useful instead) and having its own repo would be overkill IMHO.

[lminiero]

Fair point 👍

[atoppi]

IMHO this is a useful addition to the code base.

@lionelnicolas I'd suggest adding the admin endpoint as a parameter (default value should be/admin)

[lionelnicolas]

I'd suggest adding the admin endpoint as a parameter (default value should be/admin)

Done

[NFhook]

👍 use ping to do health check

[lionelnicolas]

+1 use ping to do health check

Good idea. If you want to use that for an health check, I've added -t parameter to be able to set the curl timeout, so you could set it to 1 second for example (default is 5 seconds). This will avoid curl to be stuck for a long time if your server or the network is not responding.

diff --git a/utils/janus-admin-cli b/utils/janus-admin-cli
index 5355683d..9c9a744b 100755
--- a/utils/janus-admin-cli
+++ b/utils/janus-admin-cli
@@ -13,11 +13,12 @@ janus_addr="${JANUS_HOST:-localhost}"
 janus_port="${JANUS_ADMIN_PORT:-7088}"
 janus_pass="${JANUS_ADMIN_SECRET:-janusoverlord}"
 janus_endpoint="${JANUS_ADMIN_ENDPOINT:-/admin}"
+janus_timeout="${JANUS_ADMIN_TIMEOUT:-5}"
 
 # define usage
 usage() {
        cat <<EOF
-usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e JANUS_ADMIN_ENDPOINT] [-o NAME=VALUE] -r REQUEST
+usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e JANUS_ADMIN_ENDPOINT] [-t JANUS_ADMIN_TIMEOUT] [-o NAME=VALUE] -r REQUEST
 
        -h      show this help message
        -r      janus request (required)
@@ -26,6 +27,7 @@ usage: $0 [-h] [-a JANUS_ADDR] [-p JANUS_ADMIN_PORT] [-s JANUS_ADMIN_SECRET] [-e
        -p      janus HTTP admin port (default: ${janus_port})
        -s      janus admin secret (default: ${janus_pass})
        -e      janus admin endpoint (default: ${janus_endpoint})
+       -t      janus response timeout (default: ${janus_timeout})
 EOF
 
        exit ${1:-1}
@@ -44,7 +46,7 @@ rand_str() {
 }
 
 # parse parameters
-while getopts "ha:p:s:e:o:r:" opt; do
+while getopts "ha:p:s:e:t:o:r:" opt; do
        case $opt in
                h) usage 0 ;;
                r) janus_request="${OPTARG}" ;;
@@ -53,6 +55,7 @@ while getopts "ha:p:s:e:o:r:" opt; do
                p) janus_port="${OPTARG}" ;;
                s) janus_pass="${OPTARG}" ;;
                e) janus_endpoint="${OPTARG}" ;;
+               t) janus_timeout="${OPTARG}" ;;
        esac
 done
 
@@ -103,6 +106,7 @@ curl \
        --silent \
        --fail \
        --show-error \
+       --max-time ${janus_timeout} \
        --write-out '\n' \
        --data "${http_payload}" \
        http://${janus_addr}:${janus_port}${janus_endpoint}${http_session_id}${http_handle_id}

[lminiero]

@lionelnicolas could you add some text to the Admin API documentation too, maybe as a new section there, so that people interested in the Admin API are aware of this tool they can use as an alternative to the demo page? In currently ends here in the mainpage.dox file.

[lionelnicolas]

@lionelnicolas could you add some text to the Admin API documentation too, maybe as a new section there, so that people interested in the Admin API are aware of this tool they can use as an alternative to the demo page? In currently ends here in the mainpage.dox file.

Done.

@lminiero Let me know if you want me to reword or add/remove stuff

[lionelnicolas]

bump

[lminiero]

Apologies for the awful delay in this response, I simply forgot about this... 🙈
I think it looks fine, even though there's probably a couple of things the documentation should clarify:

1. The documentation should explain that this relies on the HTTP transport for the Admin API. In fact, we have multiple transports, and so people may be confused by which one is needed (even though HTTP is mentioned in the -h of the tool).
2. It might also help to say explicitly that curl is needed for this to work, as libcurl is an optional dependency, and so not everyone may have it.
3. Looking at how the script works, this definitely supports requests that are "flat" in their structure, meaning all attributes are in the root of the JSON object. We do have requests that are nested, though, like message_plugin, query_transport and possibly others (I should really document all of them in the Admin page). Not sure if it's indeed possible to pass a child JSON object as one of the attributes: looking at the code I suspect not, but maybe adding a curly bracket to the exceptions not to add quotes (not a string) may do it? If that doesn't work, it might be better to clarify that not all methods are supported, and that those that do expect a nested object currently aren't.

As a couple of additonal notes, this seems hardcoded to plain HTTP, but some may have the Admin API exposed via HTTPS. In that case, adding a -k to skip checking certificates may be useful, since it may be HTTPS with self-signed certs.

Sorry again for this late response!

[lionelnicolas]

Sorry I missed the notification. I'll take a look by end of week.