From: George Dunlap Date: Wed, 27 Sep 2017 11:34:40 +0000 (+0100) Subject: xsatool: Update README.md with more complete usage information X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=b7cf4d4e614ef09f2dcb348647498a65ae6bd367;p=people%2Fgdunlap%2Fxsatool.git xsatool: Update README.md with more complete usage information Signed-off-by: George Dunlap --- diff --git a/README.md b/README.md index 64a9c33..0ae2b68 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,7 @@ allow the release in a nice clean order.) It should probably be obvious that creating this XSA 'recipe' (as opposed to allocating the XSA number) shouldn't be done until a patch -is reasonably close to being ready; XSA-115 provides a good reason -why. +is reasonably close to being ready. The actual creation and manipulation of the patches will be highly context-dependent and developer-driven; to that end the standard will @@ -66,10 +65,8 @@ commands to 'sync' between the trees. ## .xsatool xsatool expects a top-level directory that contains a file named -`.xsatool`. This configuration file contains paths for xen, -qemu-upstream, qemu-traditional, and xsa.git. `xsatool` will -manipulate these working trees freely, so it is highly advised that -these trees be separate from normal development trees. +`.xsatool`. This configuration file contains paths for working +repositories for xen, qemu-upstream, qemu-traditional, and xsa.git. ## xsa.git/global.meta @@ -98,21 +95,46 @@ is formatted; I've tried to format the structures such that they have reasonable-looking JSON output which can be edited by hand without too much effort if need be. -# Trees +# Working repositories and branches + +## Overview + +The developer-oriented functionality of xsatool needs access to xen, +qemu-traditional, and qemu-upstream repositories in order to test and +create patches. + +By default `xsatool` will make its own copies, so that it knows where +they are and it doesn't have to worry about interrupting a developer's +other workflows. You can, however, specify a path to existing +repositories instead. Be aware that `xsatool` may have any of the following +effects on the tree: + +- Modify the working tree (including git clean -ffdx) + +- Modify HEAD + +- Create, delete, or modify branches matching `xsa/*` + +**FIXME** Need to move test branches under xsa + +- "Fetch" from master and stable-* branches ## Branch names -When an "empty" XSA is created, two three will be created in each tree -for which patches are required: +Branches for an XSA are named by the following pattern: xsa/${n}/${v}-stable xsa/${n}/${v}-baseline xsa/${n}/${v} -`${v}` is the major release version. The `-stable` branch points to -the commit in the `stable-${v}` tree at the point at which the xsa was -created. `baseline` is `stable` with all of the prerequisite XSAs -applied. The last branch is the branch that contains the actual fix. +`${n}` is the XSA number, and `${v}` is the major release version. +The `-stable` branch points to the commit in the `stable-${v}` tree at +the point at which the xsa was created. `baseline` is `stable` with +all of the prerequisite XSAs applied. The last branch is the branch +that contains the actual fix. + +Other branches may be made as a part of operations, but will always have the +`xsa/` prefix (e.g., `xsa/tmp`). ## Generating patches from a branch @@ -154,7 +176,7 @@ rerere.enabled true`.) The `--mirrordir` or `--git-proxy` arguments can be used to specify a cache used for git clones *during build*. -## Creating or updating the initial global metadata +## Creating the initial global metadata `xsatool global update` @@ -164,17 +186,22 @@ It then goes through `xen.git` and looks for `RELEASE-M.m.p` tags, and marks each version greater than or equal to the specified version as supported. -If `global.meta` does exist, it simply does a refresh; this will -automatically add support for new versions. - # Workflow -## New Xen XSA +## Generating a new XSA Using XSA 213 as an example. +Make sure your master and stable-* branches are up to date: + +`xsatool repo update` + +Initialize the new XSA + `xsatool 213 init xen` +This command will: + - Create `xsa213.meta` with "empty" recipes for master and all currently-supported versions; in this case these versions will probably be `master`, `4.8`, `4.7`, `4.6`, and `4.5`. Tell @@ -210,7 +237,7 @@ been made. `xsatool 213 sync-patches` -For each version fro which `xsa/213/${v}` exists, this will: +For each version for which `xsa/213/${v}` exists, this will: - Delete any patches in xsa.git which match its file generation pattern. @@ -218,6 +245,53 @@ For each version fro which `xsa/213/${v}` exists, this will: - Update the recipe for that version in `xsa213.meta` +## Creating XSA metadata from existing patches + +For example, if the patches were made by a colleague. + +Make sure your master and stable-* branches are up to date: + +`xsatool repo update` + +Using XSA 228 as an example + +`xsatool 228 init xen` + +This creates an 'empty' xsa228.meta file, and the appropriate +`-stable` and `-baseline` branches. + +Now edit `xsa228.meta`. Under "Recipes", for each Xen version, there +will be an entry called "Patches" that will be an empty array (`[ ]`). +Add the name of the appropriate patch in quotes inside the brackets +for each Xen version. + +In the case of XSA 228, you'd enter `"xsa228.patch"` under both +`"master"` and `"4.9"`, `"xsa228-4.8.patch"` under `"4.8"`, `"4.7"`, +`"4.6"`, and so on. + +**TODO** + +Implement a command to do this; for example: + +`xsatool 228 set-patches 4.9 xsa228.patch` + +## Excluding a particular Xen version from an XSA + +Sometimes one of the currently-supported Xen versions isn't vulnerable +to a particular XSA. In that case, run the `xsatool init` command as +above, then manually edit the resulting metadata file and remove the +stanza for the version of Xen which doesn't need the XSA. + +**TODO** + +Implement a command to do this; for example: + +`xsatool 228 exclude 4.5` + +or: + +`xsatool 228 init --exclude=4.5 xen` + ## Checking patches before sending them out `xsatool 213 test-apply` @@ -279,6 +353,29 @@ value of the 'stable' branch (either `master` or `stable-VV`). It will then re-apply the patch and any prerequisites as-is (i.e., *not* doing a rebase), failing out in case of an error. +## Marking XSAs as published + +To mark an XSA as published (i.e., to remove XSAs from the list of +"default prerequisites" for new XSAs), edit `global.meta` and + +## Adding a new Xen release to support + +`xsatool global update` + +Assuming `global.meta` exists, this will automatically add support for +new versions. + +Alternately, the `global.meta` file can be modified directly by +copying an existing version 'stanza' and modifying the version number. + +## Removing a Xen version from support + +Edit the `global.meta` file and remove the stanza for the version no +longer supported. + +(Eventually this will be implemented by the `xsatool global +end-support [version]` command.) + # Potential future functionality ## Automatically de-duplicating patches @@ -288,6 +385,12 @@ for each supported version, even if a single patch can apply to multiple versions. Detecting this automatically would be one of the obvious next steps. +`git rev-parse {rev}:` will give you the hash of the contents of the +tree at revision `{rev}`. To see if a patch for version V is +necessary, you should be able to try applying the patch verion V+1 to +a temporary branch. If it applies, and the tree hash is the same, you +can use V+1 instead of making a patch for V. + ## Removing xsas from the 'outstanding' list Either something like: @@ -333,6 +436,12 @@ Developer checks out xsa/213/master, makes a fix, and commits it using git commi `xsatool global info` +## Exposing potentially useful lower-level functionality + +For example, if we had the functionality to check if a patch is appled: + +`xsatool cmd patch-is-applied xen.git staging-4.8 $commithash xsa231.patch` + # Open issues # Inter-tree dependcies