From f70cf6132e37e5e035895a06f8452a90d073c329 Mon Sep 17 00:00:00 2001 From: George Dunlap Date: Wed, 23 Apr 2014 14:19:43 +0100 Subject: [PATCH] docs: Give advice on dealing with quoting special characters The man page mentions passing config snippets key=val in xl create. Unfortunately, the config syntax contain characters which are interpreted (and often discarded) by the shell before getting passed in, resulting in a parsing error. For example: xl create hvm.cfg cpus="0-3" The shell will eat the quotes and pass 'cpus=0-3' to xl, which won't parse properly without the quotes. Mention this in the man page, and recommend the use of single quotes, as well as separating multiple arguments with a semicolon, thus: xl create hvm.cfg 'cpus="0-3"; pci=["1.0","1.1"]' Signed-off-by: George Dunlap Acked-by: Ian Jackson --- docs/man/xl.pod.1 | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1 index 7c03de6df1..30bd4bfc44 100644 --- a/docs/man/xl.pod.1 +++ b/docs/man/xl.pod.1 @@ -152,6 +152,12 @@ It is possible to pass I pairs on the command line to provide options as if they were written in the configuration file; these override whatever is in the I. +NB: Many config options require characters such as quotes or brackets +which are interpreted by the shell (and often discarded) before being +passed to xl, resulting in xl being unable to parse the value +correctly. A simple work-around is to put all extra options within a +single set of quotes, separated by semicolons. (See below for an example.) + =back B @@ -165,6 +171,13 @@ B This creates a domain with the file /etc/xen/DebianLenny, and returns as soon as it is run. +=item I + + xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]' + +This creates a domain with the file hvm.cfg, but additionally pins it to +cpus 0-3, and passes through two PCI devices. + =back =item B B [I] [I] @@ -186,9 +199,11 @@ Use the given configuration file. =item B -It is possible to pass I pairs on the command line to provide -options as if they were written in the configuration file; these override -whatever is in the I. +It is possible to pass I pairs on the command line to +provide options as if they were written in the configuration file; +these override whatever is in the I. Please see the note +under I on handling special characters when passing +I pairs on the command line. =back -- 2.30.2