Files, logs and API

Files of an install #

The installer links mutara and mutara-switch into /usr/local/bin and /usr/local/sbin.

The state folder #

The state folder holds:

• mutara-tls/: the self-signed certificate
• mutara-certs/: the Let's Encrypt cache
• chat/: the chat messages and files
• recordings/: the recorded clips. A clip with a transcript also has <clip>.stt.json.
• bundles/: the bundles. Each bundle has a folder bundles/<id>/ with bundle.json, the clips in clips/ (hard links or copies), and the joined audio audio.opus and audio.m4a. Read Storage and clean-up.
• voice-cache/: the copies of voice server answers
• The recent nodes, the calls that stay up through a restart, and the weather alerts
• scan-priority.json: the own scan priority of each user
• scan-list.json: the own scan list of each user (In my scan)
• user-prefs.json: the dashboard theme, the DMR ID and the M17 callsign of each user
• sessions.json: the dashboard sign-ins, as hashes of the tokens. Older versions kept it next to the configuration file; the node moves it here at start.
• install-id: the ID of the install for the transcoder server. Do not delete or change it.

Mutara finds the state folder with the first rule that applies:

1. MUTARA_STATE_DIR, if it is set.
2. STATE_DIRECTORY, which systemd sets: /var/lib/mutara for the service.
3. The working folder, if it already holds state and the folder of the configuration file does not.
4. The working folder, if it is /var/lib/mutara, as in the Docker image.
5. The folder of the configuration file.

Each node after the first keeps its recent nodes, clips, bundles, chat and favorites in modules/<node>/. A room keeps its clips, bundles and chat in modules/<id>/. A removed node moves to modules/.removed/<node>-<date>-<time>/. Mutara does not delete those files.

Logs and the journal #

• Follow the log of the service: journalctl -u mutara -f
• Read the log of an upgrade: journalctl -u mutara -u mutara-upgrade
• log.level is debug, info, warn or error. log.format is text or json.
• The diagnostics file from Settings has the recent logs, the version, the status and the settings without passwords.

Useful messages: "allstar registration failed" with the reason, and an ERROR with the stack when a node stops on an internal error.

Command-line flags #

The ASL3 importer #

mutara -import-asl3 /etc/asterisk -dry-run
sudo mutara -import-asl3 /etc/asterisk -config /etc/mutara/mutara.yaml

The importer reads rpt.conf, iax.conf and the USB channel files. It copies these items:

• the node number and password, the callsign and the timers
• the courtesy tone, the DTMF functions, the macros and the schedule
• the permanent links of startup_macro and the [nodes] entries
• the simpleusb or usbradio channel and the IAX app logins

It prints what it copied and what it skipped. It does not change the ASL3 files.

• -dry-run shows the result and writes nothing.
• -force replaces a configuration and keeps its dashboard accounts.
• -asl3-node selects the node for mutara.yaml when the setup has several nodes.
• The importer writes the node with the USB radio, or the node of -asl3-node, to mutara.yaml. It writes each other node to modules.d/<node>.yaml.

sudo mutara-switch asl3 stops Mutara and starts ASL3. sudo mutara-switch mutara does the opposite. The first time, it copies the ASL3 settings. To copy a different node, add its number: sudo mutara-switch mutara 2101. If Mutara does not start, it starts ASL3 again.

Web API #

These routes are documented for other programs. Other routes are for the dashboard and can change.

A user with clips on the module can list and play its clips. Saving a clip (download=1 or format=m4a) needs download. The list says can_download and can_delete for the user, so a client shows only the buttons that work. An older node does not send can_download: take it as true. Other requests get 403. A client must play url with the media type in type, and must not make the URL itself.

The scan stream

Open /api/scan/audio?codec=opus or ?codec=ulaw as a WebSocket. You must be signed in with listen permission. hang= (2 to 30 seconds), skip_ids=1 and list=1 are optional start values. list=1 is Scan my list; without it, the scan is Scan all. The scan and the audio of a module count in the same limit: at most 8 audio connections for each user, and 256 in total. A connection over a limit closes with code 1013 and a reason.

• The audio frames, and the ptt and agc messages, are the same as on the audio stream of one node.
• The first message is hello, with "where":"scan", "protocol":1, mode (all or list) and the list of nodes.
• A scan message comes when the scan changes. It gives module, state, active, skipped, waiting, priority, port_id, list (the modules of the scan now) and left_out (the rooms of the list that the scan left out, with the reason full or removed). The state is idle, active, hang or talk.
• priority gives the priority of each module for this user. waiting lists the active modules with a higher priority that wait because you talk back, the best first.
• A change of priority or of the scan list applies to an open scan at once. The scan does not connect again.
• port_id is the port of the scan in the status of that node. It is empty when the scan is idle.
• To control the scan, send scan (with hang_s or skip_ids), skip or unskip.

PTT talks on the node that the scan plays. If the node refuses PTT, a ptt message gives the reason: scan_idle, scan_no_tx, scan_gone, limit or busy, and in a room stopped, interrupt or threshold. On a YSF module that is busy, busy comes with "where":"reflector" and the talker of the reflector. The README of the project has the full list of messages.