Create a package share for a relay
Objective
The create_pkgs_share.py script creates, with a single command, a package share linked to a relay: a database entry, a folder on both the server and the relay, and a Syncthing folder configured on both sides.
It runs on the main Medulla server as root. It asks five questions (share name, relay, order, subject, permission) and performs the following steps:
- tests the SSH connection to
medulla@<relay name>as soon as the relay is selected; - backs up the SQL tables and Syncthing’s
config.xmlfiles to a datedbackup/folder; - creates the share folder on both the server and the relay;
- adds the share to
pkgs.pkgs_sharesand its access rule topkgs.pkgs_rules_local; - adds a Syncthing configuration to the main server and the relay.
If a step fails before completion, everything that has already been done is undone. The --dry-run option simulates the entire process without writing anything: use this before the first actual run.
Prerequisites
You need root access on the main server, a medulla account on the relay that is reachable via SSH using a key, and Syncthing installed on both sides.
Download the script
Directly from this link:
https://dl.medulla-tech.io/ma/create_pkgs_share.py
Or by running the following command:
wget https://dl.medulla-tech.io/ma/create_pkgs_share.py
Main server (where the script is run)
- Root access. The script changes the owner of the created folder and writes to Syncthing’s
config.xmlfile. - Syncthing must be installed, with a file located at
/var/lib/syncthing/.config/syncthing/config.xml. - Directory: the directory is created in
/var/lib/pulse2/packages/sharing/, which must already exist. - Existing
syncthingaccount and group. - Resolvable relay name: the
nameservervalue ofxmppmaster.relayservermust be resolvable from the main server (DNS or/etc/hosts).
Relay
medullaaccount accessible via SSH using a key (see the following section).- root, or passwordless sudo for
medulla. - Syncthing installed, with the same
config.xmlfile and the samepulsemaster_globalsection. The template copied to the relay is the relay’s, not the server’s. - Directory
/var/lib/pulse2/packages/sharing/must exist, and thesyncthingaccount and group must be present. aclpackage (optional): withoutgetfaclandsetfacl, the folder is created without ACLs (no+inls -l), with a warning.
Network
- The main server connects to the relay via SSH (port 22 by default; use the
--relay-ssh-portoption for a different port). - No password is required during execution: the SSH connection is key-based only.
If password-based authentication is disabled on the relay, manually add the public key to ~medulla/.ssh/authorized_keys (.ssh directory set to 700, file set to 600, owner medulla).
1. Test under the same conditions as the script
From the main server, as root:
ssh -o BatchMode=yes medulla@<relay name> 'sudo -n sh -c true && echo "SSH + sudo OK"'
The message SSH + sudo OK should appear without any prompts. If SSH prompts you or asks for a password, the script will fail in the same way.
For a different account, port, or key, use the script’s --relay-ssh-user, --relay-ssh-port, and --relay-ssh-key options.
Installing the script
The script consists of a single file: install the packages, copy it to the main server, then verify that it starts.
1. Copy the script
In a folder reserved for root, for example /root/scripts/:
mkdir -p /root/scripts
cp create_pkgs_share.py /root/scripts/
chmod +x /root/scripts/create_pkgs_share.py
The backup/ folder is created next to the script on the first actual run. The copies of config.xml it contains include the Syncthing API key: the script’s folder must not be readable by any accounts other than root.
2. Verify
/root/scripts/create_pkgs_share.py --help
The help message should appear. If the message Module manquant : pymysql appears, install the python3-pymysql package.
Usage
Run the script on the main server as root: without any arguments, it will ask its questions one by one, display a summary, and then ask for confirmation before writing anything. Always start with a simulation.
/root/scripts/create_pkgs_share.py --dry-run # simulation, rien n'est écrit
/root/scripts/create_pkgs_share.py # lancement réel
Before the five questions, the script prompts for the missing SQL username or password after checking the options, the PKGS_DB_PASSWORD variable (password only), and then the xmppmaster.ini file.
The five questions
|
No. |
Question |
Expected answer |
Default |
|---|---|---|---|
|
1 |
Public name of the share |
Free-form text; spaces and uppercase letters are allowed. Preserved as-is in |
Empty: the relay name |
|
2 |
ID of the relay to use |
The ID displayed in the list from |
None |
|
3 |
Order of the new rule |
An integer. Existing rules (ID, order, share, subject, permission) are displayed before the prompt. |
Last order + 10 |
|
4 |
Subject |
|
|
|
5 |
Permission |
|
None: required response |
Example: the response Mon Partage Test results in comments = Mon Partage Test, name = mon_partage_test, a folder and a share_path /var/lib/pulse2/packages/sharing/mon_partage_test, and a Syncthing folder with ID pulsemaster_mon_partage_test.
The summary ends with Confirmer la création ? [o/N]: the default answer is no.
If the relay is unreachable, the script displays the error and then asks, Continuer sans configurer le relai ? [o/N] (default is no). Answering yes creates the share on the server side only; the relay must still be configured manually. With --yes, the script exits without writing anything.
Simulation (--dry-run)
The script asks the same questions and connects to the database and the relay, but only in read-only mode: no backups, no folders, no INSERT, and no changes to config.xml. It displays the two INSERT queries with their values, the folder that would be created, and the XML blocks that would be added to Syncthing, both on the server side and on the relay side. The actual share ID is recalculated at the time of writing. If the relay is unreachable, the simulation displays a warning and continues.
Non-interactive mode
A value provided as an argument is not requested again. With all values specified and the --yes option, the script asks no questions:
/root/scripts/create_pkgs_share.py \
--name "Partage Relai 01" --relay-id 3 \
--order 5 --subject '.*' --permission rw --yes
Options: responses and behavior
|
Option |
Role |
|---|---|
|
|
Simulates all actions without writing anything. |
|
|
No final confirmation. If the relay is unreachable, the script stops instead of asking the question. |
|
|
Public name of the share (question 1). |
|
|
Relay ID (question 2). |
|
|
Rule order (question 3). |
|
|
Rule subject (question 4). |
|
|
|
|
|
Does not configure the relay: no SSH connection is attempted. |
Options: paths and permissions
By default, these options should not be changed.
|
Option |
Role |
Default |
|---|---|---|
|
|
Parent directory of the shares on the server. |
|
|
|
Owner and group of the created folder, on the server and on the relay. |
|
|
|
Permissions for the created folder, in octal. |
|
|
|
Folder whose ACLs are copied (same path on the server and on the relay). |
|
|
|
Syncthing's |
|
|
|
ID of the |
|
Options: relay (SSH) and database
By default, these options should not be changed.
|
Option |
Role |
Default |
|---|---|---|
|
|
SSH account on the relay. |
|
|
|
SSH port on the relay. |
Default SSH port |
|
|
SSH private key to use. |
Default key for the account running the script |
|
|
SSH option passed to |
None |
|
|
SSH connection timeout, in seconds. |
|
|
|
Syncthing's |
|
|
|
Parent directory of shares on the relay. |
|
|
|
SQL host. |
INI file, otherwise |
|
|
SQL port. |
INI file; otherwise, |
|
|
SQL user. |
INI file, otherwise prompted |
|
|
SQL password. Prefer the |
INI file (same user), otherwise prompted |
What the script modifies
For a share named Mon Partage Test on the relai01 relay (ID 3), the script writes the following six items. Nothing else is affected.
|
No. |
Where |
What |
|---|---|---|
|
1 |
|
One row: |
|
2 |
|
One row: algorithm |
|
3 |
Main server, share folder |
Creates |
|
4 |
Main server, Syncthing’s |
Adds a |
|
5 |
Relay, share folder |
Same folder, same permissions, and same ACLs as on the server (via SSH and |
|
6 |
Relay, Syncthing's |
Adds a |