utils: add helper to interact with janus admin API

src/mainpage.dox

@@ -2600,6 +2600,142 @@ POST /admin/12345678/98765432
 	"transaction" : "<random alphanumeric string>",
 	"admin_secret" : "<password specified in janus.jcfg, if any>"
 }
+\endverbatim
+ *
+ * \section admincli Admin CLI tool
+ * In the source repository, you will find the \c utils/janus-admin-cli tool.
+ * This is a simple shell script able to interact with the admin API. It could
+ * be useful for live-enabling \c locks and \c refcount debugging on production,
+ * or to start a PCAP dump, or live-update the log level, especially when the
+ * admin API is not easily accessible (e.g. janus running in a kubernetes pod).
+ *
+ * \par Usage
+ * Janus admin connection can be configured using CLI parameters or environment
+ * variables:
+ *
+\verbatim
+usage: utils/janus-admin-cli [-h] [options] -r REQUEST
+
+	-h	show this help message
+	-r	janus request (required)
+	-o	janus request optional parameter (can be repeated) (default: none)
+	-a	janus server address (default: localhost, env: JANUS_HOST)
+	-p	janus HTTP admin port (default: 7088, env: JANUS_ADMIN_PORT)
+	-s	janus admin secret (default: janusoverlord, env: JANUS_ADMIN_SECRET)
+	-e	janus admin endpoint (default: /admin, env: JANUS_ADMIN_ENDPOINT)
+	-t	janus response timeout (default: 5, env: JANUS_ADMIN_TIMEOUT)
+\endverbatim
+ *
+ * The \c -r parameter is used to select which \ref adminreq you want to send.
+ * Then you can use the \c -o parameter multiple times to specify arguments for
+ * your request.
+ *
+ * \par Examples
+\verbatim
+user@host:~$ janus-admin-cli -r ping
+{
+  "janus": "pong",
+  "transaction": "aNexVTIgcYbc"
+}
+\endverbatim
+\verbatim
+user@host:~$ janus-admin-cli -r set_log_level -o level=5
+{
+  "janus": "success",
+  "transaction": "D1sGjlV3KLnm",
+  "level": 5
+}
+\endverbatim
+\verbatim
+user@host:~$ janus-admin-cli -r list_sessions
+{
+  "janus": "success",
+  "transaction": "GgaL0xmUbBI4",
+  "sessions": [
+    3236169122271256,
+    295460503767564,
+    5854530659370442,
+    5714856303331417,
+    4512308604273274,
+    3642487421981464,
+    8938575577523615
+  ]
+}
+\endverbatim
+\verbatim
+user@host:~$ janus-admin-cli -r list_handles -o session_id=3236169122271256
+{
+  "janus": "success",
+  "session_id": 3236169122271256,
+  "transaction": "rR4lYK1hZTuB",
+  "handles": [
+    8548304105222430
+  ]
+}
+\endverbatim
+\verbatim
+user@host:~$ 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": []
+  }
+}
+\endverbatim
+\verbatim
+user@host:~$ janus-admin-cli -r start_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430 -o folder=/tmp
+{
+  "janus": "success",
+  "transaction": "ZPPhyQqNfLwp"
+}
+\endverbatim
+\verbatim
+user@host:~$ janus-admin-cli -r stop_pcap -o session_id=3236169122271256 -o handle_id=8548304105222430
+{
+  "janus": "success",
+  "transaction": "mm74LKsRVaKW"
+}
 \endverbatim
  *
  */

utils/janus-admin-cli

@@ -0,0 +1,112 @@
+#!/bin/sh
+
+# exit on failure
+set -e
+
+# exit on unassigned variable
+set -u
+
+# variables
+janus_request="none"
+janus_options="none"
+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] [options] -r REQUEST
+
+	-h	show this help message
+	-r	janus request (required)
+	-o	janus request optional parameter (can be repeated) (default: ${janus_options})
+	-a	janus server address (default: ${janus_addr}, env: JANUS_HOST)
+	-p	janus HTTP admin port (default: ${janus_port}, env: JANUS_ADMIN_PORT)
+	-s	janus admin secret (default: ${janus_pass}, env: JANUS_ADMIN_SECRET)
+	-e	janus admin endpoint (default: ${janus_endpoint}, env: JANUS_ADMIN_ENDPOINT)
+	-t	janus response timeout (default: ${janus_timeout}, env: JANUS_ADMIN_TIMEOUT)
+EOF
+
+	exit ${1:-1}
+}
+
+# define fatal
+fatal() {
+    printf "fatal: $*\n\n" >&2
+    usage 1
+}
+
+# get random string
+rand_str() {
+	length=${1:-32}
+	LC_CTYPE=C tr -dc 'a-zA-Z0-9' < /dev/urandom | fold -w ${length} | head -n 1
+}
+
+# parse parameters
+while getopts "ha:p:s:e:t:o:r:" opt; do
+	case $opt in
+		h) usage 0 ;;
+		r) janus_request="${OPTARG}" ;;
+		o) janus_options="${janus_options},${OPTARG}" ;;
+		a) janus_addr="${OPTARG}" ;;
+		p) janus_port="${OPTARG}" ;;
+		s) janus_pass="${OPTARG}" ;;
+		e) janus_endpoint="${OPTARG}" ;;
+		t) janus_timeout="${OPTARG}" ;;
+	esac
+done
+
+# check parameters
+if [ "${janus_request}" = "none" ]; then
+	fatal "Janus request parameter is mandatory"
+fi
+
+# parse optional parameter
+http_session_id=
+http_handle_id=
+http_payload_opts=""
+for opt in $(echo ${janus_options} | sed 's/,/ /g'); do
+	if [ "${opt}" = "none" ]; then
+		continue
+	fi
+
+	opt_name="$(echo ${opt} | cut -d= -f1)"
+	opt_value="$(echo ${opt} | cut -d= -f2-)"
+
+	# append double-quotes to JSON strings
+	if echo "${opt_value}" | grep -qE '^([0-9]+|true|false|null)$'; then
+		http_payload_opts="${http_payload_opts}\"${opt_name}\": ${opt_value},"
+	else
+		http_payload_opts="${http_payload_opts}\"${opt_name}\": \"${opt_value}\","
+	fi
+
+	if [ "${opt_name}" = "session_id" ]; then
+		http_session_id="/${opt_value}"
+	elif [ "${opt_name}" = "handle_id" ]; then
+		http_handle_id="/${opt_value}"
+	fi
+done
+
+# prepare payload
+http_payload=$(cat <<EOF
+{
+	"janus": "${janus_request}",
+	${http_payload_opts}
+	"transaction": "$(rand_str 12)",
+	"admin_secret": "${janus_pass}"
+}
+EOF
+)
+
+# send request
+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}