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 :+1:

[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