Oresat Linux Updater
Total Page:16
File Type:pdf, Size:1020Kb
OreSat Linux Updater Ryan Medick Apr 22, 2021 CONTENTS 1 Glossary of Terms Used 3 2 OreSat Linux Updater Daemon5 2.1 Daemon..................................................5 3 Update Maker 9 3.1 Update Maker..............................................9 4 Files 11 4.1 Update Archive.............................................. 11 4.2 Status Archive.............................................. 13 5 Internals 15 5.1 OreSat Linux Updater’s Internal..................................... 15 6 Indices and tables 23 Index 25 i ii OreSat Linux Updater Warning: This is still a work in progress. CONTENTS 1 OreSat Linux Updater 2 CONTENTS CHAPTER ONE GLOSSARY OF TERMS USED D-Bus Inter-process communication system provided by systemd. See https://www.freedesktop.org/wiki/Software/ dbus/ Daemon Long running, background process on Linux. dpkg The low level package manager for install and removing packages on Debian Linux. APT is build ontop of it. OreSat PSAS’s open source CubeSat. See https://www.oresat.org/ OreSat Linux Manager (OLM) The front end daemon for all OreSat Linux boards. It converts CANopen message into DBus messages and vice versa. See https://github.com/oresat/oresat-linux-manager OreSat Linux Updater The common daemon found on all OreSat Linux boards, that handles updating the board with update archives. Status Archive A tar file with two status files produced by the OreSat Linux updater. One with a JSON list of the update archive in OreSat Linux updater’s cache and the other will be a copy of dpkg status file. The Update Maker will uses these to make future update archives. Update Archive A tar file used by the OreSat Linux updater daemon to update the board it is running on. It will contain deb package files and bash script. These will be made the the Updater Maker. 3 OreSat Linux Updater 4 Chapter 1. Glossary of Terms Used CHAPTER TWO ORESAT LINUX UPDATER DAEMON A common daemon on all Linux boards that allows board to updated over D-Bus using update files. 2.1 Daemon A backend service for updating the Linux board using deb packages and bash scripts. It is mostly a D-Bus server with a update file cache, that can run update files from the Update Maker. Basics: • Giving the daemon update file will not trigger an update, only when the Update D-Bus method is called will an update start. • The daemon can also generate status file that can be used to make future updates and to know what is install on the board. • If a update fails the update file cache will be clear as it is assume all future updates require older updates. To start the daemon, if the Debian package is installed. $ sudo systemctl start oresat-linux-updaterd 2.1.1 State Machine If the board is powerred off when the Updater is updating, it will try resume the update next time the daemon is started. class oresat_linux_updater.dbus_server.State(value) The states oresat linux updaer daemon can be in. STANDBY = 0 Waiting for commands. 5 OreSat Linux Updater UPDATE = 1 Updating. UPDATE_FAILED = 2 Update failed, cache was cleared STATUS_FILE = 3 Making the status tar file. 2.1.2 D-Bus API class oresat_linux_updater.dbus_server.DBusServer(work_dir: str, cache_dir: str, log- ger: logging.Logger) The D-Bus Server wrapper ontop oresat linux updater that handles all threading. Note: all D-Bus Methods, Properties, and Signals follow Pascal case naming. Parameters • work_dir (str) – Archivepath to working directory. • cache_dir (str) – Archivepath to update archive cache directory. • logger (logging.Logger) – The logger object to use. StatusArchive D-Bus Signal with a str that will sent the absolute path to the updater status file after the MakeStatusArchive D-Bus Method is called. Type str UpdateResult D-Bus Signal with a Result value that will be sent after an update has finished or failed. Type uint8 AddUpdateArchive(update_archive: str) ! bool D-Bus Method that copies an update archive into the update archive cache. Parameters update_archive (str) – The absolute path to update archive for the updater to store. Returns True if a file was added or False on failure. Return type bool property AvailableUpdateArchives D-Bus Property for the number of update archives in cache. Readonly. Type uint32 property InstructionCommand D-Bus Property for current instruction command. Will be an empty str if not updating. Readonly. Type str property InstructionIndex D-Bus Property for current index in the instructions. Wil be 0 if not updating. Readonly. Type uint8 property ListUpdates D-Bus Property for get the list of update filename in the cache. Readonly. Type str 6 Chapter 2. OreSat Linux Updater Daemon OreSat Linux Updater MakeStatusArchive() ! str D-Bus Method to make status tar file with a copy of the dpkg status file and a file with the list of update archives in cache. Returns Filepath to new file or empty str. Return type str property StatusName D-Bus Property for the curent status as a State name. Readonly. Type str property StatusValue D-Bus Property for the curent status as a State value. Readonly. Type uint8 property TotalInstructions D-Bus Property for the number intruction in the current update. Will be 0 if not updating. Readonly. Type uint8 Update() ! bool D-Bus Method to load the oldest update archive in cache and runs update. Returns True if a the updater will start to update or False on failure. Return type bool property UpdateArchive D-Bus Property for the current update archive. Will be a empty str if the daemon is not currently updating. Readonly. Type str 2.1. Daemon 7 OreSat Linux Updater 8 Chapter 2. OreSat Linux Updater Daemon CHAPTER THREE UPDATE MAKER A shell interface for making update files. 3.1 Update Maker TDB 9 OreSat Linux Updater 10 Chapter 3. Update Maker CHAPTER FOUR FILES File used by or created by the OreSat Linux updater dameon or Update Maker. 4.1 Update Archive An update archive is tar file that will be used by the OreSat Linux Updater daemon to update the Linux board the daemon is running on. The update maker will be used to generate these files. 4.1.1 Compression Update files are a tar file compressed with xz. xz is used as it offers a great compression ratio and the extra compression time doesn’t matter, since the update archive will be generated on a ground station server. 4.1.2 Tar Name The file name will follow filename standards for oresat-linux-manager (OLM) with the keyword set to “update”. See https://oresat-linux.readthedocs.io/en/latest/standards/file-transfer.html for more info on OLM file name standards. Example, a update to the GPS board: gps_update_1612392143.tar.xz The date field in the filename will be used to determine the next file to used as the oldest file is always run first. 4.1.3 Tar Contents The update archive will always include a instructions.txt file. It can also include deb files (debian package files), bash script, and/or files to be used by bash scripts as needed. Example contents of a update archive: instructions.txt package1.deb package2.deb package3.deb bash_script1.sh bash_script2.sh bash_script3.sh bash_script2_external_file 11 OreSat Linux Updater 4.1.4 instructions.txt instruction.txt contatins a JSON string with with a list of instruction dictionaries with type and items fields. The instructions will be run in order. class oresat_linux_updater.instruction.InstructionType(value) All the valid instruction types for the instructions.txt file. BASH_SCRIPT = 0 Run a bash scripts. SUPPORT_FILE = 1 One or more support files that will by used by a bash script. DPKG_INSTALL = 2 Install one or more packages with dpkg. DPKG_REMOVE = 3 Remove one or more packages with dpkg. DPKG_PURGE = 4 Purge one or more packages with dpkg. Example instructions.txt: [ { "type":"DPKG_INSTALL", "items":["package1.deb"] }, { "type":"BASH_SCIPT", "items":["bash_script1.sh"] }, { "type":"BASH_SCIPT", "items":["bash_script2.sh"] }, { "type":"DPKG_INSTALL", "items":["package2.deb","package3.deb"] }, { "type":"DPKG_REMOVE", "items":["package4"] }, { "type":"BASH_SCIPT", "items":["bash_script3.sh"] } { "type":"DPKG_PURGE", "items":["package5","package6"] }, { "type":"SUPPORT_FILE", "items":["bash_script2_external_file"] } ] 12 Chapter 4. Files OreSat Linux Updater 4.2 Status Archive A status archive is a .tar.xz archive file that contains two files; a olu-status txt file and dpkg-status txt file. The oresat_linux_updater daemon will make this if the MakeStatusFile dbus method is called. After every update, a OLU status file should be made and sent to the ground station, so future update can be made. The OLU status tar files will be around 100KiB. 4.2.1 OLU Status txt File This file will contain a JSON list of update archive files that are in the cache and are available to be installed. Note: If the cache is empty the status txt file will contain “null”. Example OLU status file: [ "gps_update_1612392143.tar.xz", "gps_update_1612381721.tar.xz" ] 4.2.2 DPKG Status txt File A copy of the dpkg status file (/var/lib/dpkg/status) that will be used by the update maker to make future updates to the board. Example dpkg status file: Package: adduser Status: install ok installed Priority: important Section: admin Installed-Size: 849 Maintainer: Debian Adduser Developers<adduser @packages.debian.org> Architecture: all Multi-Arch: foreign Version: 3.118 Depends: passwd, debconf (>= 0.5)| debconf-2.0 Suggests: liblocale-gettext-perl, perl Conffiles: /etc/deluser.conf 773fb95e98a27947de4a95abb3d3f2a2 Description: add and remove users and groups This package includes the'adduser' and 'deluser' commands for creating and removing users. -'adduser' creates new users and groups and adds existing users to existing groups; -'deluser' removes users and groups and removes users froma given group. Adding users with 'adduser' is much easier than adding them manually. Adduser will choose appropriate UID and GID values, create a home directory, copy skeletal user configuration, and automate setting initial values for the user's password, real name and so on.