-
Notifications
You must be signed in to change notification settings - Fork 47
sdm Plugins
Plugins are a modular way to extend sdm capabilities. Plugins are similar to custom phase scripts, and can work during customization or when burning an SSD/SD Card.
It makes sense to include some plugins into the IMG you're creating (e.g., postfix, samba) so they are installed onto every system burned from that IMG, but some are typically installed once per network (e.g., apt-cacher-ng), or not needed on every system. In that case you can use the plugin when burning the SSD/SD for that specific system.
The initial set of plugins provided with sdm includes: apt-cacher-ng, apt-file, clockfake, postfix, rxapp, samba, and vnc.
Other plugins are planned. If there are any specific plugins you're interested in, let me know!
You can add your own plugins as well. Put the plugin in /usr/local/sdm/local-plugins, and it will be automatically found. sdm looks at local-plugins first, so you can override an sdm-provided plugin with your modifications if desired.
You can also specify the plugin name with a full path. sdm will copy the plugin to /usr/local/sdm/local-plugins if it does not exist or the one specified is newer than the one in local_plugins.
Specify each plugin with a separate --plugin switch:
sdm --plugin samba:"args" --plugin postfix:"args" . . .
Multiple --plugin switches are allowed on the command line.
The complete plugin switch format is as follows. See below for plugin-specific examples.
--plugin plugname:"key1=val1|key2=val2|key3=val3"
Enclose the keys/values in double quotes as above if there is more than one key/value or bash will be confused by the "|".
apt-cacher-ng installs the RasPiOS apt-cacher-ng service into the IMG or onto the SSD/SD card (If used with --burn).
NOTE: All arguments are optional
- gentargetmode — Possible values: 'Set up once', 'Set up now and update later', and 'No automated setup'. [Default: 'No automated setup']. TBH not sure what this does. If you figure it out, let me know ;)
- bindaddress — the IP address to which the server should bind. [Default: 0.0.0.0], which is all IP addresses on the server.
- cachedir — apt-cacher-ng directory. [Default: /var/cache/apt-cacher-ng]
- port — TCP port [Default: 3142]
- tunnelenable —Do not enable this. [Default: false]
- proxy —TBH not sure what this does. If you figure it out, let me know ;)
The default apt-cacher-ng server install uses port 3142. apt-cacher-ng will be enabled by sdm FirstBoot and ready to process requests after the FirstBoot process completes.
apt-file installs the apt-file command and builds the database. This is very handy for looking up apt-related information.
There are no --plugin arguments for apt-file
btwifiset is a service that enables WiFi SSID and password configuration over Bluetooth using an iOS app. Once the service is running, you can use the BTBerryWifi iOS app to connect to the service running on your Pi and configure the WiFi. See https://github.com/nksan/Rpi-SetWiFi-viaBluetooth for details on btwifiset itself.
- country — The WiFi country code. This argument is mandatory
- localsrc — Locally accessible directory where the btwifiset.py can be found, instead of downloading from GitHub
- btwifidir — Directory where btwifiset will be installed. [Default: /usr/local/btwifiset]
- timeout — After timeout seconds the btwifiset service will exit [Default: 15 minutes]
- logfile — Full path to btwifiset log file [Default: Writes to syslog]
The fake-hwclock provided with RasPiOS runs hourly as a cron job. clockfake does the same thing as fake-hwclock, but you control the interval, and it's always running. Lower overhead, less processes activated, and more control. What could be better? ;)
- interval — Interval in minutes between fake hardware clock updates
postfix installs the postfix mail server. This plugin installs the postfix server but at the moment doesn't do too much to simplify configuring postfix. BUT, once you have a working /etc/postfix/main.cf, it can be fed into this plugin to effectively complete the configuration.
- maincf — The full /path/to/main.cf for an already-configured /etc/postfix/main.cf. If provided, it is placed into /etc/postfix after postfix has been installed.
- mailname — Domain name [Default: NoDomain.com]
- main_mailer_type — Type of mailer [Default: Satellite system]
- relayhost — Email relay host DNS name [Default: NoRelayHost]
-
--plugin postfix:"maincf=/path/to/my-postfix-main.cf— Uses a fully-configured main.cf, and postfix will be ready to go. -
--plugin postfix:"relayhost=smtp.someserver.com|mailname=mydomain.com|rootmail=myemail@somedomain.com— Set some of the postfix parameters, but more configuration will be required to make it operational. A good reference will be cited here at some point.
rxapp is a handy tool to securely and remotely start X11 apps via SSH without a password. You can read about it here.
rxapp is included because it is generally useful, but also as a demonstration of how to copy a file from the network (GitHub in this case) into the IMG in a plugin.
There are no --plugin arguments for rxapp
- smbconf — Full /path/to/smb.conf for an already-configured /etc/samba/smb.conf. If provided it is placed into /etc/samba after samba has been installed.
- shares — Full /path/to/shares.conf for a file containing only the samba share definitions. If provided it is appended to /etc/samba/smb.conf after samba has been installed.
- dhcp — TBH not sure what this does. If you figure it out, let me know ;)
- do_debconf — TBH not sure what this does. If you figure it out, let me know ;)
- workgroup — Workgroup name to replace WORKGROUP in the default /etc/samba/smb.conf. If smbconf is specified, the workgroup is NOT modified.
-
--plugin samba:smbconf=/home/bls/mylan-smb.conf— Use the provided fully-configured file for /etc/samba/smb.conf -
--plugin samba:"shares=/home/bls/mysmbshares.conf"— Append the provided share definitions to the end of the default /etc/samba/smb.conf -
--plugin samba:"workgroup=myworkgroup|shares=/home/bls/mysmbshares.conf"— Use the default /etc/samba/smb.conf, set the workgroup name to myworkgroup and append the provided share definitions to /etc/samba/smb.conf
- realvnc=resolution — Install RealVNC server with the specified resolution on the console. The resolution is optional.
- tigervnc=res1,res2,...resn — Install tigervnc server with virtual VNC servers for the specified resolutions
- tightvnc=res1,res2,...resn — Install tightvnc server with virtual VNC servers for the specified resolutions
Only one of tigervnc or tightvnc can be installed and configured on a system by sdm.
-
--plugin vnc:"realvnc|tigervnc=1280x1024,1600x1200— Install RealVNC server for the console and tigervnc virtual desktop servers for the specified resolutions. -
--plugin vnc:"realvnc=1600x1200"— Install RealVNC server and configure the console for 1600x1200, just as raspi-config VNC configuration does. -
--plugin vnc:"tigervnc=1024x768,1600x1200,1280x1024"— Install tigervnc virtual desktop servers for the specified resolutions. Only configure RealVNC if it is already installed (e.g., RasPiOS with Desktop IMG).
wsdd is the Web Service Discovery host daemon. It's very useful in Windows/Samba environments. You can read about it at https://github.com/christgau/wsdd
- wsddswitches=switchlist — List of switches to write into /etc/default/wsdd
- localsrc=/path/to/files — Local directory with cached copy of wsdd (files: wsdd.py wsdd.8 wsdd.defaults wsdd.service)
sdm-plugin-template can be used to build your own plugin. It contains some code in Phase 0 demonstrating some of the things you can do with the plugin_getargs function and how to access the results.
Take a copy of sdm-plugin-template, rename it to your plugin's name, and edit that copy.
The code in the template for Phase 0 is sample code to show how to parse the arguments and print them out. Other than that, you can write bash code to implement your plugin.
plugin_getargs parses the plugin arguments and returns them in bash variables. For instance, for --plugin foo:"key1=abc|key2=def" plugin_getargs will create the bash variable key1 with the value abc, and the bash variable key2 with the value def.
plugin_getargs also defines the varible keysfound which is a list of the keys found, separated by vertical bars (e.g. "|key1|key2|").
plugin_getargs plugin-name argument-list valid-keys required-keys
Where:
- plugin-name — Plugin name for messages. The default sdm-plugin-template uses the plugin filename.
- argument-list — The argument list passed to the plugin
- valid-keys — [Optional] Vertical bar-separated list of valid keynames. If provided, keys in the argument list that are not in the valid-keys list are flagged with a message
- required-keys — [Optional] Vertical bar-separated list of required keynames. If provided, keys in the required-keys list that are not present in the argument list are flagged with a message
plugin_printkeys formats the retrieved argument data and prints it on the console and into the sdm history log. It expects the following variables set, which should happen by default.
- pfx — The plugin name
- foundkeys — The list of keys found in the argument list, created by plugin_getargs
- And the variables as described above in plugin_getargs
The output from plugin_getargs looks like this in /etc/sdm/history:
2022-11-01 19:32:24 > Plugin postfix: Keys/values found:
2022-11-01 19:32:24 relayhost: mail.mydomain.com
2022-11-01 19:32:24 mailname: mydomain.com
2022-11-01 19:32:24 rootmail: myemail@somedomain.com
plugin_dbgprint is like logtoboth, but with two exceptions:
- The line is only printed if
--plugin-debugwas specified on the command line - The line is printed with "D!Plugin plugin-name: " preceding the message text
For instance:
2022-11-01 19:32:24 D!Plugin sdm-plugin-template: Test printout from sdm-plugin-template