Skip to main content

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:

  1. tests the SSH connection to medulla@<relay name> as soon as the relay is selected;
  2. backs up the SQL tables and Syncthing’s config.xml files to a dated backup/ folder;
  3. creates the share folder on both the server and the relay;
  4. adds the share to pkgs.pkgs_shares and its access rule to pkgs.pkgs_rules_local;
  5. 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.xml file.
  • 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 syncthing account and group.
  • Resolvable relay name: the nameserver value of xmppmaster.relayserver must be resolvable from the main server (DNS or /etc/hosts).

Relay

  • medulla account accessible via SSH using a key (see the following section).
  • root, or passwordless sudo for medulla.
  • Syncthing installed, with the same config.xml file and the same pulsemaster_global section. The template copied to the relay is the relay’s, not the server’s.
  • Directory /var/lib/pulse2/packages/sharing/ must exist, and the syncthing account and group must be present.
  • acl package (optional): without getfacl and setfacl, the folder is created without ACLs (no + in ls -l), with a warning.

Network

  • The main server connects to the relay via SSH (port 22 by default; use the --relay-ssh-port option 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 comments; the characters / and \ are not allowed.

Empty: the relay name

2

ID of the relay to use

The ID displayed in the list from xmppmaster.relayserver. The script then tests the SSH connection to medulla@<nameserver>.

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

.* for everyone, or a user's name.

.*

5

Permission

rw (read/write) or r (read-only).

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

--dry-run

Simulates all actions without writing anything.

-y, --yes

No final confirmation. If the relay is unreachable, the script stops instead of asking the question.

--name

Public name of the share (question 1).

--relay-id

Relay ID (question 2).

--order

Rule order (question 3).

--subject

Rule subject (question 4).

--permission

r or rw (question 5).

--skip-relay

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

--sharing-root

Parent directory of the shares on the server.

/var/lib/pulse2/packages/sharing

--share-owner USER[:GROUP]

Owner and group of the created folder, on the server and on the relay.

syncthing:syncthing

--share-mode

Permissions for the created folder, in octal.

755

--acl-from

Folder whose ACLs are copied (same path on the server and on the relay).

<sharing-root>/global

--syncthing-config

Syncthing's config.xml file on the server.

/var/lib/syncthing/.config/syncthing/config.xml

--syncthing-template-id

ID of the <folder> copied as a template, on both the server and the relay.

pulsemaster_global

Options: relay (SSH) and database

By default, these options should not be changed.

Option

Role

Default

--relay-ssh-user

SSH account on the relay.

medulla

--relay-ssh-port

SSH port on the relay.

Default SSH port

--relay-ssh-key

SSH private key to use.

Default key for the account running the script

--ssh-option

SSH option passed to -o, repeatable. Example: StrictHostKeyChecking=accept-new.

None

--ssh-timeout

SSH connection timeout, in seconds.

10

--relay-syncthing-config

Syncthing's config.xml file on the relay.

/var/lib/syncthing/.config/syncthing/config.xml

--relay-sharing-root

Parent directory of shares on the relay.

/var/lib/pulse2/packages/sharing

--db-host

SQL host.

INI file, otherwise localhost

--db-port

SQL port.

INI file; otherwise, 3306

--db-user

SQL user.

INI file, otherwise prompted

--db-password

SQL password. Prefer the PKGS_DB_PASSWORD variable: an argument is visible in ps.

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

pkgs database, pkgs_shares table

One row: id = last id + 1, name = mon_partage_test, comments = Mon Partage Test, type = local, uri and ars_name = relay name, ars_id = relay id, share_path = /var/lib/pulse2/packages/sharing/mon_partage_test.

2

pkgs database, pkgs_rules_local table

One row: algorithm 1, order, subject, and permission entered, pkgs_shares_id = ID of the row above.

3

Main server, share folder

Creates /var/lib/pulse2/packages/sharing/mon_partage_test with permissions drwxr-xr-x+ syncthing syncthing: owner, group, mode 755, and ACLs copied from global.

4

Main server, Syncthing’s config.xml

Adds a <folder> block copied from pulsemaster_global.

5

Relay, share folder

Same folder, same permissions, and same ACLs as on the server (via SSH and sudo).

6

Relay, Syncthing's config.xml

Adds a <folder> block copied from the relay’s own pulsemaster_global (not the server’s).