Xen Document Days/TODO

Requested Documentation

Feel free to comment on items using the following convention:

* {{Comment|~~~~:}} your comment

Feel free to add new workitems using the following convention:

==== Workitem ===
~~~~: work-item description

In progress (just need to double check whether finished)

A Xen Performance Tuning Guide

Which workloads work for which virt mode. Network considerations. NUMA. VCPU Pinning. Etc.
Examples from the KVM world: Guest perf tuning, KVM options affecting performance, Comprehensive guide covering pinning, caching, memory, huge pages, etc.
Lars.kurth 19:50, 25 June 2012 (UTC): Work has been done on Tuning. Not sure whether more needs to be done.
Stefano 30 June 2012: The guide is in a decent state but I will keep improving it during the next doc days.
Lars.kurth 15:54, 19 September 2012 (UTC): Needs a quick sanity check for Xen 4.2
Lars.kurth 12:48, 22 January 2013 (UTC): Is this done?

Better Statements on Compatibility

There seems to be some confusion in the wider Linxu community about XL/XM compatibility. Maybe some specific questions in an FAQ/the release notes. Also migration compatibility comes up often. Any articles related to compatibility should be listed in Category:Compatibility, which I am willing to clean up.

Anthony 14:33, 26 November 2012 (UTC): I add a bunch of pages to the category, and add few link in the category to upgrade from xend to xl.
Anthony 17:19, 26 November 2012 (UTC): I also redirect XL in Xen 4.2 to XL as they had both the same content minus few things.
Lars.kurth 12:48, 22 January 2013 (UTC): Is this done?
Ijc 16:39, 25 January 2013 (UTC): I think we also need to cover compatibility confusion about 3.x vs 4.x.

Better XCP Overview Documentation

Lars.kurth 08:02, 25 September 2012 (UTC): See XCP Overview & XCP Release Features - these need a little bit more work

Easy tasks for Beginners

You may weant to read Wiki Help if you do not have an account.

Migrate useful blog posts to wiki

Sift through blog.xen.org and copy useful posts to wiki. This will mainly be a reformatting exercise. Before you copy an article, perform a search on the wiki (headline or key word) to see whether the post exists already. If in doubt, ask on the IRC channel.

Fix articles that need attention

Category:Contains_Needs_Formatting - Pages that need formatting
Category:Contains_Needs_Action - Pages that need fixing. Go through these, and if you get stuck ask people on the IRC channel for help, or go to the next page.
Category:Contains_TODO - Pages that have a TODO item on the page. Go through these, and if you get stuck ask people on the IRC channel for help, or go to the next page.

Review Categorization

Sometimes new pages on the wiki are not created with categories. You can find these by going to Special:UncategorizedPages. Documentation about which category is used where can be found in Categories for Authors. If in doubt ask on IRC.

Pages With Comments or Improvement Suggestions

We ask users to highlight issues using talk pages, following the conventions outlined in Help:Talk Pages. Comments made using these conventions can be identified using the Category:Pages with comments.

Missing Pages

Special:WantedPages - You can find missing pages by going to this link. There are several courses of actoin that can be taken:
- The page is needed : Add {{TODO|With a comment}} to the top of the page
- The page is not needed : Remove the reference to the page (follow the link in the bracket besides the page)
- Note that the list of Wanted pages contains lots of needed translations and categories, which you can ignore
- If in doubt, ask for help on the IRC channel

Open work items

Document release signing keys and fingerprints etc

We should publish the key ids and fingerprints somewhere.

UEFI Secure Boot

Write a document on how to sign the xen binary for UEFI Secure Boot. Potential reference here: Dealing With Secure Boot

Manpages for xe command

Write manpages for xe and it's 361 subcommands.

A team led by Grant McWilliams and including Matthew Spah, Lisa Nguyen and Mike Webber is currently working on documenting the xe command and will continue to do so until completed. Moving the source repo to xen-org has been [proposed].

Xen PV Architecture Documentation

Something like a SDM for Xen PV "processors".

Add pages to Category:Paravirtualised Architecture

X86 Paravirtualised Memory Management
- Needs OS specifics adding (e.g. Linux paravirt_ops)
Grant Tables
Event Channels
I/O (blk in OK shape, net could catch up)
...

Describe the different ways, and necessary components, to create PVs using xl

Raised by mail by Matthias Blankenhaus (who is prepared to take the lead, but needs help): This document would describe the different ways, and necessary components that each way requires, to create PVs using xl. Right now there are at least the following cases:

loopbacked vhds
- single partition format
- disk format
qemu backed vhds
- qcow / qcow2
LVS backed image

This is not a complete list. Also the mileage of each case differs depending on the kernel features enabled in dom0/domu and also depending on the Xen version. Furthermore, certain format require additional infrastructure like the tap device.

All in all, this a complex topic that needs clarification. Doing this based on the lowest common denominator, xl, would clarify many things. In addition, baseline performance data on all of the above would help a great deal. Matthias volunteered to run the majority of needed perf tests

A Xen Security Guide

The different options in Xen for Security, trade-offs, how to set them up, how to test Xen for security and how to optimize for different scenarios

Lars.kurth 09:48, 27 March 2012 (UTC): Category:Security contains some security related docs
Lars.kurth 11:01, 4 April 2012 (UTC): It would be good if we could document a) XSM, b) Introspection API, c) Xen and SELinux in Dom0, d) Memory Access API (introduced in 4.1)
User Docs that where migrating content would make sense and update such as (we can attach PDF's to the wiki now for starters, or we can use a conversion tool
- http://bits.xensource.com/Xen/docs/user.pdf
Lars.kurth 15:59, 19 September 2012 (UTC): Some good articles came out of XenSummit NA (these can be built upon). Got funding to document XSM; contract in place, but contractor is currently ill.

Review and Update: xenpm usage recommendations

There is Xen power management and Xenpm command which may all be outdated. These should probably be reviewed and updated.

HOWTO : using xm trigger to poweroff or firing off NMIs

Howto on using xm trigger to poweroff or firing off NMIs.

HOWTO : How to Set Up Nested Virtualization

See this thread

HOWTO: Chain pypxeboot and pygrub

How to chain pypxeboot and pygrub

Lars.kurth 10:35, 27 March 2012 (UTC): Is pypxeboot popular at all?
Fheigl: I added that. It is somewhat common, OVM 2 and OVM 3 rely on it for PXE installs. I'm not sure if xenpvnetboot is the same, or works. The use case is "you want to use the same installation server for Xen VMs and phys. servers. You want to be able to reinstall them based on PXE reply.
Fheigl: There is documentation for pypxeboot, but there is no (afaik) documentation for how pygrub is used as a fallback loader. We wasted many days just to get some hack that can't even load a newer kernel. Which sucks, in the end you spend more time/money making PV PXE boot work than you save by using virtualized servers.
Fheigl: How could it be popular given the state of documentation. <= Key issue to the left of this sentence.
Lars.kurth 16:03, 19 September 2012 (UTC): wondering whether this video contains what is needed

Updated docs for transition to git

We are planning to switch the primary Xen repositories to git at some point, a bunch of documentation will necessarily require updating.

Submitting Xen Patches
Compiling Xen From Source
Presumably numerous other places...

Developer Docs

Docs that need attention or are missing

Make XAPI docs (built from source) available on xen.org
PVOPS portal on xen.org - Konrad volunteered
some more xenstore docs (i.e. recent python bindings that were sent to the -users list
Using libxenstat python bindings (imo they're broken)
More PV protocol docs (see recent patches to blkif.h for example)
Document xenstore paths used by guests and toolstack etc
- Ijc 16:10, 26 November 2012 (UTC): This is now in tree: http://xenbits.xen.org/docs/unstable/misc/xenstore-paths.html

Done Recently

cpupools intro / howto

George Dunlap: See Cpupools_Howto

Clear up Xen TODO List

Setting_boot_order_for_domUs
XenDevelopmentProjects - although this will need maintaining
Revamp http://wiki.xen.org/wiki/Xen_PCI_Passthrough. Should be more organized, easier to follow, less verbose, more thorough, and more up-to-date.
Review and update http://en.wikipedia.org/wiki/Xen - in particular the "Host: Unix-like systems" is out-of-date. The Guest section is too.
Make Host Install and Guest Install more useful
- Lars.kurth: Note: both pages share Template:Distro_Resources
- Docs for many distros are missing: identify what docs are missing or out of date and put them on the todo list
Feature Status Doc : Xen_Release_Features
Xen Overview which explains the top level architectural features and options, trade-offs and links to examples tutorials that show how you set these up
List i.e. stuff what to test after packaging. This would avoid the current state of affairs where most distros are infact broken w/re to Xen. See Distros
Installation Guides: How to install on various distros. Tag with Category:Host Install and Category:Guest_Install.
Tuning
vcpu pinning (part of Tuning)

Document Policy on Maintenance Releases

Which releases are supported, for how long. Owners. As well as a mechanism for individuals (or vendors) to take ownership of older releases (as is the case for Xen 3.4).

Ijc 16:07, 26 November 2012 (UTC): Attempt to document current process: http://lists.xen.org/archives/html/xen-devel/2012-11/msg01389.html
Lars.kurth 12:48, 22 January 2013 (UTC): Is this done, see Xen_Maintenance_Releases?
Ijc 14:01, 22 January 2013 (UTC): Doc is complete and patches to reference it are in the various trees.

Document {deb,rpm,tar}-pkg targets in kernel

Mainline_Linux_Kernel_Configs talks about the obsolete and Debian specific make-kpkg tool. Should reference the kernels own foo-pkg targets instead.

Ijc 12:12, 28 January 2013 (UTC): Done. Made a bunch of other cleanups too.