{ "info": { "author": "Corey Minyard", "author_email": "cminyard@mvista.com", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: MIT License", "Operating System :: OS Independent" ], "description": "# tuf_manifest\n\nThis package provided authenticated delivery of files using manifest\nfiles for specifying what to deliver.\n\nEach manifest file version is numbered sequentially from 1. The\ntarget will keep track of the last manifest file transferred (using 1\nfor the initial version). When it checks the repository, it will\nattempt to transfer new manifest files by version number until it\nfinds the last one. The target will then compare it to it's last\nmanifest file. It will transfer any new or updated files, create\na list of new, updated, and deleted files, and transfer that to\nanother tool to do the actual updating.\n\nThe manifest file will be a file that is list of names and versions\nand filenames, one set on each line.\n\n## How to use this\n\nThis code should make it easier to handle delivery of update content\nusing tuf. tuf itself is not an updater, it is an authenticated file\ntransfer mechanism. This code takes it a step closer to being an\nupdate mechanism by automatically transferring files required for an\nupdate and calling a program with those file names and whether they\nare new or need to be updated. It also supplies names that have been\ndeleted.\n\n### Delivery types\n\nThree possible ways this can be used: package delivery, update deltas,\nand full update delivery.\n\n#### Package delivery\n\nFor updates involving a package management system like RPM or dpkg,\neach manifest file will contain all the packages to be installed on\nthe target for that version. When a new manifest file comes out, the\nupdate handler program will be called by tuf-manifest will packages to\nbe added, updated, and deleted. These files will already be\ndownloaded and ready, it's just a matter of applying them.\n\nThe difficulty here comes in the manifest management. But build\nsystems like yocto can automatically generate these types of manifests\nfrom the build.\n\nFor atomicity, something like rpm-ostree can make the updates install\natomically to avoid issues with reboots or shutdowns during an update.\n\n#### Update deltas\n\nFor updates that involve a blob being applied to be appended to an\nexisting install, like an ostree binary or clear linux update, each\nmanifest will have all the previous installs plus the new update\nappended to the end. tuf-manifest will call the update handler with\nall the new updates to be installed, already downloaded and ready.\n\n#### Full updates\n\nFor full image updates, each manifest will have one file (or a set of\nfiles if multiple images are involved) in it: the update file(s) with\nthe same name(s) and a new version. tuf-manifest will deliver the\nupdate to the update handler.\n\n### Setting up the repo host\n\nThe first thing you need to do is create a TUF repo. This is not\ncovered here, it is a complex task whose steps depend on your security\nrequirements. See the TUF documentation for that.\n\nAfter you have an initial repo created, you need the tufrepo and keys\n(without the root keys, of course, for best security).\n\nYou also need to create a manifest file in the form:\n\n \n\nOne line per package. The filename is not the full path to the file,\njust the name. You need to have all the files someplace, too.\n\nThe manifest file put into the repository, too, so it's name is\nimportant. It must match what the client has set in its configuration\nfile, and it must end in a . that is sequentially increasing from 1.\nThe client looks for the filename. sequentially from it's current\nsetting, so this is important.\n\nOnce you have everything ready, run:\n\n gitm-repo --load-manifest --manifest \\\n --manifest-dir \n\nThe files are loaded into the manifest.\n\nSo, for a simple example, lets say we have the following manifest file:\n\n a 1.0 a-1.0.pack\n a-info 1.0 a-info-1.0.txt\n\nin $HOME/builda/manifest.1, and we have $HOME/builda/files/a-1.0.pack\nand $HOME/builda/info/a-info-1.0.txt. You would cd to the repository\nand run:\n\n tufm-repo --load-manifest --manifest $HOME/builda/manifest.1 \\\n --manifest-dir $HOME/builda/files $HOME/builda/info\n\nand a-1.0.pack and a-info-1.0.txt will be put into the repository.\n\nIf you come out with a new version, you need to create the next\nmanifest file version for it, lets say:\n\n a 1.0 a-1.0.pack\n b 2.0 b-2.0.pack\n b-info 2.0 b-info-2.0.txt\n\nand name it $HOME/builda/manifest.2. Then run:\n\n tufm-repo --load-manifest --manifest $HOME/builda/manifest.1 \\\n --manifest-dir $HOME/builda/files $HOME/builda/info\n\nand b-2.0.pack and b-info-2.0.txt will be added. Note that\na-info-1.0.txt will not be deleted from the repository, it's just not\nin the second manifest. When the client fetches manifest.2, it will\nsee that a-info is gone and b and b.info are added.\n\n#### Maintaining timestamps in the repo\n\nThe file timestamps for the timestamp and snapshot file expire often\nby default, 1 day for timestamp and 7 days for snapshots. The\nstandard repo command from tuf does not have a method to update this,\nso tufm-repo has added one. Do:\n\n tufm-repo --update-timestamp --role --expires