-
Notifications
You must be signed in to change notification settings - Fork 48
Programming plugins and custom phase scripts
This section provides context and details about the sdm environment for writing plugins and custom phase scripts.
sdm provides plugins and custom phase scripts with 3 operating environments:
-
Phase 0, or mounted disk environment: This environment runs in the context of the host (like pretty much every other script that you run). The disk or IMG that sdm is operating on is mounted in the host OS. Since the directory name can change, sdm provides the environment variable $SDMPT that always points to the top of the directory tree.
Thus, a correct reference to a file in the IMG in the mounted disk environment is
$SDMPT/etc/rc.localIf you don't include $SDMPT, you will access or modify files on your host operating system.System management commands such as systemctl, journalctl, and pretty much every other command affect the host OS. This is probably not what you want to do! You can, however, access the network, host storage, mounted network shares, etc.
Keep work in this environment minimized to copying needed files from the host OS into the IMG somewhere. You can copy files directly to target locations in the IMG, prefaced by $SDMPT, or you can stage files into $SDMPT/etc/sdm/local-assets if desired.
-
Phase 1, or Container environment: This environment runs in a container that is isolated from the host OS. The container file system is,er, contained, and code running in the container cannot access the host OS file system. $SDMPT is not needed so is unset. This means that you can safely reference it in this environment, since $SDMPT/etc/rc.local and /etc/rc.local are equivalent. But it is not required, like it is for the Phase 0 mounted disk environment.
-
post-install: The post-install phase environment is the same as Phase 1. The difference between Phase 1 and the post-install phase is the timing of when they are run.
Phase 1 starts when the container is entered. At the conclusion of Phase 1, sdm performs an
apt update. After that completes sdm runs plugin and custom phase script Phase 1 code.After Phase 1 for plugins and custom phase scripts completes, sdm runs the apps/xapps installs, and then enters the post-install phase.
Work done in the post-install phase is typically focused on configuring the just-installed packages. After sdm completes its post-install work, the plugin and custom phase script post-installs are called. Note that anything that can be done in the Container environment can be done in post-install. This includes installing more packages, if you determine you need do it there for some reason.
Think about the environments described above, rather than phases. sdm creates an environment that is the same as that of the Phase 0 environment, and then calls selected plugins to run Phase 0.
Similarly, it creates a Container environment and runs the Phase 1 and post-install code for plugins.
Most plugin code doesn't need to know that it's running as part of a burn operation. For code that does, the env var $SDMNSPAWN can be inspected. It's value will be "Burn0" when a plugin is running Phase 0 during a burn operation. It will be set to "Burn1" in Phase 1 and post-install code. (In a standard customize operation, SDMNSPAWN will be "Phase0" during Phase 0, and "Phase1" during Phase 1 and post-install phases.)
b0script/b1script use the same technique.
Start with the file /usr/local/sdm/plugins/sdm-plugin-template. Copy it somewhere, give it a new filename, and work on it.
Start with the file /usr/local/sdm/sdm-customphase, and similarly, copy it somewhere with a new filename, and work on it.
If you run into problems, logtoboth is your friend. It will write the string to the console and $SDMPT/etc/sdm/history.
Remember that sdm copies itself into the IMG during customization phase 0. If you change any of the sdm files, it's easiest on your brain if you start over and re-customize. More than once I've been mystified why my change didn't work, because I tried to shortcut some steps.
sdm keeps all the context in /etc/sdm/cparams, which is read by each module (via $SDMPT/etc/sdm/sdm-readparams), so that all variables are defined.
-
--1pibootconf-file — $pi1bootconf -
--appsapplist — $apps -
--xappsapplist — $xapps -
--apipIPADDR — $apip -
--apssidssidname — $apssid -
--apt-dist-upgrade — $aptdistupgrade -
--aptcacheIPADDR — $aptcache -
--aptmaintoptions — $aptmaint -
--autologin— $autologin -
--batch— $batch -
--b0scriptscript — $b0script -
--b1scriptscript — $b1script -
--bootaddkey:value,key:value,... — $bootadd -
--bootconfigkey:value,key:value,... — $bootconfig -
--bootsetkey:value,key:value,.. — $bootset -
--bootscripts— $bootscripts -
--cron-dfile — $crond -
--cron-dailyfile — $crondaily -
--cron-hourlyfile — $cronhourly -
--cron-monthlyfile — $cronmonthly -
--cron-weeklyfile — $cronweekly -
--cron-systemd— $cronsystemd -
--cscriptscript — $cscript -
--csrcdir — $csrc -
--custom[1-4]str — $custom[1-4] -
--datefmtstr — $datefmt -
--ddswstr — $ddsw -
--debugapt — $debugs -
--disablearg,arg — $disables -
--directory— $fdirtree=1 -
--dhcpcdfile — $dhcpcd -
--dhcpcdwait— $dhcpcdwait -
--domainname — $domain -
--dtoverlay— $dtoverlay -
--dtparam— $dtparam -
--ecolorsfg:bg:cur — $ecolors -
--eepromstr — $eeprom -
--expand-root— $expandroot=1 -
--exportsfile — $exports -
--extend— $fextend=1 -
--fstabfile — $fstab -
--groupslist — $groups -
--hdmi-force-hotplug— $hdmiforcehotplug=1 -
--hdmi-ignore-edid— $hdmiignoreedid=1 -
--hdmigroupn — $hdmigroup=n -
--hdmimoden — $hdmimode=n -
--hosthostname — $hname -
--hotspotconfig — $hotspot -
--journaltype — $journal -
--keymapkeymapname — $keymap -
--L10n— $loadl10n=1 -
--loadlocalargs — $loadlocal -
--localelocalename — $locale -
--logwidthN — $logwidth -
--lxde-configfiles — $lxdeconfig -
--mcolorsfg:bg:cur — $mcolors -
--modprobefile — $modprobe -
--motdfile — $motd -
--mouseleft — $fmouse=1 -
--nouser— $nouser=1 -
--nowait-timesync— $nowaittimesync=1 -
--nspawnswstr — $nspawnsw -
--password-pipwd — $passwordpi -
--password-userpwd — $passworduser -
--password-rootpwd — $passwordroot -
--password-samey|n — $samepwd -
--pluginpname:"args" — $plugins -
--plugin-debug— $plugindebug -
--poptionsstr — $poptions -
--redact— $redact=1 -
--norestart— $noreboot=1 -
--rclocalstring — $rclocal -
--rebootn — $rebootwait=n, $reboot=1 -
--redact— $redact=1 -
--redo-customize— $redocustomize=1 -
--regen-ssh-host-keys— $regensshkeys=1 -
--restart— $rebootwait=20, $reboot=1 -
--rootpwd— $rootpwd -
--sdmdir/path/to/sdm — $sdmdir -
--showapt— $showapt=1 -
--showpwd— $showpwd=1 -
--sshnone|socket|service — $ssh -
--swapn — $swapsize -
--svcdisablesvc1,svc2,... — $svcdisable -
--svc-disable svc1,svc2,... — $svcdisable -
--svcenablesvc1,svc2,... — $svcenable -
--svc-enablesvc1,svc2,... — $svcenable -
--sysctlfile — $sysctl -
--systemd-configitem:file,... — $systemdconfig -
--timezonetzname — $timezone -
--udevfile — $udev -
--uiduid — $myuid -
--userusername — $myuser -
--vncbasen — $vncbase -
--wifi-countrycountry — $wificountry -
--wpawpaconf — $wpa -
--nowpa— $fnowpa=1 -
--xmbn — $imgext