ia64/xen-unstable

changeset 15630:9c3a8ca0bf34

[MAN] Explanation of recent extensions to xm security subcommands
Signed-off-by: Stefan Berger <stefanb@usa.ibm.com>
author kfraser@localhost.localdomain
date Thu Jul 19 17:18:20 2007 +0100 (2007-07-19)
parents e934846666e6
children bb5c23bbc7b7
files docs/man/xm.pod.1
line diff
     1.1 --- a/docs/man/xm.pod.1	Thu Jul 19 17:17:25 2007 +0100
     1.2 +++ b/docs/man/xm.pod.1	Thu Jul 19 17:18:20 2007 +0100
     1.3 @@ -822,13 +822,15 @@ security in Xen, you must compile Xen wi
     1.4  described under "Configuring Security" below. There, you will find
     1.5  also examples of each subcommand described here.
     1.6  
     1.7 -=item B<makepolicy> I<policy>
     1.8 +=item B<setpolicy> ACM I<policy> I<[--load|--boot]>
     1.9  
    1.10 -Compiles the XML source representation of the security I<policy>. It
    1.11 -creates a mapping (.map) as well as a binary (.bin) version of the
    1.12 -policy. The compiled policy can be loaded into Xen with the
    1.13 -B<loadpolicy> subcommand or can be configured to be loaded at boot
    1.14 -time with the B<cfgbootpolicy> subcommand.
    1.15 +Makes the given ACM policy available to xend as a I<xend-managed policy>.
    1.16 +The policy is compiled and a mapping (.map) as well as a binary (.bin)
    1.17 +version of the policy is created. If the option I<--load> is provided
    1.18 +the policy is loaded into Xen. If the option I<--boot> is provided the
    1.19 +system is configure to be loaded with the policy at boot time. If these
    1.20 +options are not provided with the B<setpolicy> subcommand, the
    1.21 +B<activatepolicy> subcommand provides this functionality.
    1.22  
    1.23  =over 4
    1.24  
    1.25 @@ -843,18 +845,26 @@ global policy root directory.
    1.26  
    1.27  =back
    1.28  
    1.29 -=item B<loadpolicy> I<policy>
    1.30 -
    1.31 -Loads the binary representation of the I<policy> into Xen. The binary
    1.32 -representation can be created with the B<makepolicy> subcommand.
    1.33 +=item B<activatepolicy> I<[--load|--boot]>
    1.34  
    1.35 -=item B<cfgbootpolicy> I<policy> [I<boot title>]
    1.36 +Activates the xend-managed policy by loading it into Xen using the
    1.37 +I<--load> option or configures the system to boot with the
    1.38 +xend-managed policy during the next reboot as a result of the
    1.39 +I<--boot> option. The latter is only supported if the system is booted
    1.40 +with the grub boot loader and the default boot title is modified.
    1.41 +It copies the binary policy representation into the /boot directory and
    1.42 +adds a module line specifying the binary policy to the /boot/grub/menu.lst
    1.43 +or /boot/grub/grub.conf file.
    1.44  
    1.45 -Configures I<policy> as the boot policy for Xen. It copies the binary
    1.46 -policy representation into the /boot directory and adds a module line
    1.47 -specifying the binary policy to the /boot/grub/menu.lst file. If your
    1.48 -boot configuration includes multiple Xen boot titles, then use the
    1.49 -I<boot title> parameter to specify a unique part of the proper title.
    1.50 +=item B<getpolicy> [--dumpxml]
    1.51 +
    1.52 +Displays information about the current xend-managed policy, such as
    1.53 +name and type of the policy, the uuid xend has assigned to it on the
    1.54 +local system, the version of the XML representation and the status
    1.55 +of the policy, such as whether it is currently loaded into Xen or
    1.56 +whether the policy is automatically loaded during system boot. With
    1.57 +the I<--dumpxml> option, the XML representation of the policy is
    1.58 +displayed.
    1.59  
    1.60  =item B<dumppolicy>
    1.61  
    1.62 @@ -869,28 +879,47 @@ is 'dom'. The labels are arranged in alp
    1.63  
    1.64  =item B<addlabel> I<label> B<dom> I<configfile> [I<policy>]
    1.65  
    1.66 +=item B<addlabel> I<label> B<mgt> I<domain name> [I<policy type>:I<policy>]
    1.67 +
    1.68  =item B<addlabel> I<label> B<res> I<resource> [I<policy>]
    1.69  
    1.70 +=item B<addlabel> I<label> B<vif-idx> I<domain name> [I<policy type>:I<policy>]
    1.71 +
    1.72 +
    1.73  Adds the security label with name I<label> to a domain
    1.74 -I<configfile> (dom) or to the global resource label file for the
    1.75 -given I<resource> (res). Unless specified, the default I<policy> is the
    1.76 -currently enforced access control policy. This subcommand also
    1.77 -verifies that the I<policy> definition supports the specified I<label>
    1.78 -name.
    1.79 +I<configfile> (dom), a Xend-managed domain (mgt), to the global resource label
    1.80 +file for the given I<resource> (res), or to a managed domain's virtual network
    1.81 +interface (vif) that is specified by its index. Unless specified,
    1.82 +the default I<policy> is the currently enforced access control policy.
    1.83 +This subcommand also verifies that the I<policy> definition supports the
    1.84 +specified I<label> name.
    1.85 +
    1.86 +The only I<policy type> that is currently supported is I<ACM>.
    1.87  
    1.88  =item B<rmlabel> B<dom> I<configfile>
    1.89  
    1.90 +=item B<rmlabel> B<mgt> I<domain name>
    1.91 +
    1.92  =item B<rmlabel> B<res> I<resource>
    1.93  
    1.94 +=item B<rmlabel> B<vif-idx> I<domain name>
    1.95 +
    1.96  Works the same as the B<addlabel> command (above), except that this
    1.97 -command will remove the label from the domain I<configfile> (dom) or
    1.98 -the global resource label file (res).
    1.99 +command will remove the label from the domain I<configfile> (dom),
   1.100 +a Xend-managed domain (mgt), the global resource label file (res),
   1.101 +or a managed domain's network interface (vif).
   1.102  
   1.103  =item B<getlabel> B<dom> I<configfile>
   1.104  
   1.105 +=item B<getlabel> B<mgt> I<domain name>
   1.106 +
   1.107  =item B<getlabel> B<res> I<resource>
   1.108  
   1.109 -Shows the label for the given I<configfile> or I<resource>
   1.110 +=item B<getlabel> B<vif-idx> I<domain name>
   1.111 +
   1.112 +Shows the label for a domain's configuration in the given I<configfile>,
   1.113 +a xend-managed domain (mgt), a resource, or a managed domain's network
   1.114 +interface (vif).
   1.115  
   1.116  =item B<resources>
   1.117  
   1.118 @@ -908,12 +937,9 @@ B<CONFIGURING SECURITY>
   1.119  
   1.120  =over 4
   1.121  
   1.122 -In xen_source_dir/Config.mk set the following parameters:
   1.123 +In xen_source_dir/Config.mk set the following parameter:
   1.124  
   1.125      ACM_SECURITY ?= y
   1.126 -    ACM_DEFAULT_SECURITY_POLICY ?= \
   1.127 -        ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
   1.128 -
   1.129  Then recompile and install xen and the security tools and then reboot:
   1.130  
   1.131      cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
   1.132 @@ -922,26 +948,26 @@ Then recompile and install xen and the s
   1.133  
   1.134  =back
   1.135  
   1.136 -B<COMPILING A SECURITY POLICY>
   1.137 +B<SETTING A SECURITY POLICY>
   1.138  
   1.139  =over 4
   1.140  
   1.141 -This step creates client_v1.map and client_v1.bin files in
   1.142 -/etc/xen/acm-security/policies/example/chwall_ste.
   1.143 +This step makes the policy available to xend and creates the client_v1.map and
   1.144 +client_v1.bin files in /etc/xen/acm-security/policies/example/chwall_ste.
   1.145  
   1.146 -    xm makepolicy example.chwall_ste.client_v1
   1.147 +    xm setpolicy ACM example.client_v1
   1.148  
   1.149  =back
   1.150  
   1.151 -B<LOADING A SECURITY POLICY>
   1.152 +B<ACTIVATING THE XEND-MANAGED SECURITY POLICY>
   1.153  
   1.154  =over 4
   1.155  
   1.156 -This step activates client_v1.bin as new security policy in Xen. You
   1.157 -can use the dumppolicy subcommand before and afterwards to see the
   1.158 +This step activates the xend-manged policy as new security policy in Xen.
   1.159 +You can use the dumppolicy subcommand before and afterwards to see the
   1.160  change in the Xen policy state.
   1.161  
   1.162 -    xm loadpolicy example.chwall_ste.client_v1
   1.163 +    xm activatpolicy --load
   1.164  
   1.165  =back
   1.166  
   1.167 @@ -949,11 +975,11 @@ B<CONFIGURING A BOOT SECURITY POLICY>
   1.168  
   1.169  =over 4
   1.170  
   1.171 -This configures the boot loader to load client_v1.bin at boot
   1.172 -time. During system start, the ACM configures Xen with this policy and
   1.173 +This configures the boot loader to load the current xend-managed policy at
   1.174 +boot time. During system start, the ACM configures Xen with this policy and
   1.175  Xen enforces this policy from then on.
   1.176  
   1.177 -    xm cfgbootpolicy example.chwall_ste.client_v1
   1.178 +    xm activatepolicy --boot
   1.179  
   1.180  =back
   1.181  
   1.182 @@ -964,7 +990,7 @@ B<LISTING SECURITY LABELS>
   1.183  This subcommand shows all labels that are defined and which can be
   1.184  attached to domains.
   1.185  
   1.186 -    xm labels example.chwall_ste.client_v1 type=dom
   1.187 +    xm labels example.client_v1 type=dom
   1.188  
   1.189  will print for our example policy:
   1.190  
   1.191 @@ -1019,6 +1045,28 @@ permitted".
   1.192  
   1.193  =back
   1.194  
   1.195 +B<ATTACHING A SECURITY LABEL TO A XEND-MANAGED DOMAIN>
   1.196 +
   1.197 +=over 4
   1.198 +
   1.199 +The addlabel subcommand supports labeling of domains that are managed
   1.200 +by xend. This includes domains that are currently running, such as for
   1.201 +example Domain-0, or those that are in a dormant state.
   1.202 +Depending on the state of the system, it is possible that the new label
   1.203 +is rejected. An example for a reason for the rejection of the relabeling
   1.204 +of a domain would be if a domain is currently allowed to
   1.205 +access its labeled resources but due to the new label would be prevented
   1.206 +from accessing one or more of them.
   1.207 +
   1.208 +    xm addlabel dom_Fun mgt Domain-0
   1.209 +
   1.210 +This changes the label of Domain-0 to dom_Fun under the condition that
   1.211 +this new label of Domain-0 would not prevent any other domain from
   1.212 +accessing its resources that are provided through Domain-0, such as for
   1.213 +example network or block device access.
   1.214 +
   1.215 +=back
   1.216 +
   1.217  B<ATTACHING A SECURITY LABEL TO A RESOURCE>
   1.218  
   1.219  =over 4
   1.220 @@ -1072,9 +1120,11 @@ B<LISTING LABELED RESOURCES>
   1.221      xm resources
   1.222  
   1.223        phy:hda6
   1.224 +            type: ACM
   1.225            policy: example.chwall_ste.client_v1
   1.226            label:  res_LogicalDiskPartition1(hda1)
   1.227        file:/xen/disk_image/disk.img
   1.228 +            type: ACM
   1.229            policy: example.chwall_ste.client_v1
   1.230            label:  res_LogicalDiskPartition2(hda2)
   1.231  
   1.232 @@ -1094,19 +1144,19 @@ consistent to achieve predictable securi
   1.233  The XML version is the version that users are supposed to create or
   1.234  change, either by manually editing the XML file or by using the Xen
   1.235  policy generation tool (B<xensec_gen>). After changing the XML file,
   1.236 -run the B<makepolicy> subcommand to ensure that these changes are
   1.237 -reflected in the other versions. Use, for example, the subcommand
   1.238 -B<cfgbootpolicy> to activate the changes during the next system
   1.239 +run the B<setpolicy> subcommand to ensure that the new policy is
   1.240 +available to xend. Use, for example, the subcommand
   1.241 +B<activatepolicy> to activate the changes during the next system
   1.242  reboot.
   1.243  
   1.244  The binary version of the policy is derived from the XML policy by
   1.245  tokenizing the specified labels and is used inside Xen only. It is
   1.246 -created with the B<makepolicy> subcommand. Essentially, the binary
   1.247 +created with the B<setpolicy> subcommand. Essentially, the binary
   1.248  version is much more compact than the XML version and is easier to
   1.249  evaluate during access control decisions.
   1.250  
   1.251  The mapping version of the policy is created during the XML-to-binary
   1.252 -policy translation (B<makepolicy>) and is used by the Xen management
   1.253 +policy translation (B<setpolicy>) and is used by xend and the management
   1.254  tools to translate between label names used as input to the tools and
   1.255  their binary identifiers (ssidrefs) used inside Xen.
   1.256  
   1.257 @@ -1121,5 +1171,6 @@ B<xmdomain.cfg>(5), B<xentop>(1)
   1.258    Sean Dague <sean at dague dot net>
   1.259    Daniel Stekloff <dsteklof at us dot ibm dot com>
   1.260    Reiner Sailer <sailer at us dot ibm dot com>
   1.261 +  Stefan Berger <stefanb at us dot ibm dot com>
   1.262  
   1.263  =head1 BUGS