diff --git a/doc/sync-cmd.1 b/doc/sync-cmd.1 new file mode 100644 index 0000000..f457f98 --- /dev/null +++ b/doc/sync-cmd.1 @@ -0,0 +1,253 @@ +.\" Automatically generated by Pandoc 2.5 +.\" +.TH "SYNC\-CMD" "1" "" "Version 1.0" "Synchronizer Command Shell" +.hy +.SH NAME +.PP +\f[B]sync\-cmd\f[R] \[em] Command shell for administrating an OpenXT +system. +.SH SYNOPSIS +.PP +\f[B]sync\-cmd\f[R] [\f[B]command\f[R] [\f[B]\f[BI]arguments\f[B]\f[R]]] +.SH DESCRIPTION +.PP +Provides a command shell with an acceptable level of remote +administrative capabilities. +.SH BUILTIN COMMANDS +.SS xenmgr +.PP +Used to interact and manage xenmgr process. +.TP +.B release +Print the OpenXT release information for the current running software. +.TP +.B config +Provides two subcommands to interact with xenmgr config. +.PP +\ \ \ \ \ \ \ \f[B]\f[BI]subcommands:\f[B]\f[R] +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ get \f[I]property\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Retrieves \f[I]property\f[R] from xenmgr config. +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ set \f[I]property\f[R] \f[I]value\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Stores \f[I]value\f[R] in \f[I]property\f[R] of +xenmgr config. +.TP +.B vms +List all VMs on the system. +.TP +.B create_vm \f[I]template name\f[R] [\f[I]json file\f[R]] +Create a VM using the specified template and populate its config using +the optional JSON file. +.TP +.B delete_vm \f[I]identifier\f[R] +Delete a VM identified by identifier, where identifier may be the UUID +or the name of the VM. +.TP +.B upgrade \f[I]URL\f[R] +Initiate a platform upgrade using the OTA file located at \f[I]URL\f[R]. +.TP +.B reboot +Reboot the system. +.TP +.B shutdown +Shutdown the system. +.SS upgrade +.PP +Alias to \f[B]xenmgr upgrade\f[R] +.SS vm [\f[I]identifier\f[R]] +.PP +Used to interact and manage VM instances. +.TP +.B select [\f[I]identifier\f[R]] +In interactive mode, this selects the VM to act upon for subsequent +commands. +.TP +.B domstore +Provides two subcommands to configure a domains domstore. +.PP +\ \ \ \ \ \ \ \f[B]\f[BI]subcommands:\f[B]\f[R] +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ get \f[I]key\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Retrieves \f[I]key\f[R] from domstore. +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ set \f[I]key\f[R] \f[I]value\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Stores \f[I]value\f[R] for \f[I]key\f[R] in +domstore. +.TP +.B argo_firewall +Provides three subcommands to configure a domains argo firewall. +.PP +\ \ \ \ \ \ \ \f[B]\f[BI]subcommands:\f[B]\f[R] +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ list +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Retrieves all the firewall rules. +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ add \f[I]rule\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Add \f[I]rule\f[R] to the firewall. +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ delete \f[I]rule\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ If \f[I]rule\f[R] matches an existing rule, delete +it. +.TP +.B disks +List all disks associated with the VM. +.TP +.B disk +Provides subcommands to manage a disk associated with the VM. +.PP +\ \ \ \ \ \ \ \f[B]\f[BI]subcommands:\f[B]\f[R] +.PD 0 +.P +.PD +.PD 0 +.P +.PD +\ \ \ \ \ \ \ replace \f[I]URL\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \ \ Replace the backing disk image with one downloaded +from \f[I]URL\f[R]. +.SS usb +.PP +Used to manage the USB policy. +.TP +.B list +List all the rules in the USB policy. +.TP +.B show \f[I]num\f[R] | \f[I]all\f[R] +Display \f[I]num\f[R] rule in the USB policy, \f[I]all\f[R] will display +all rules. +.TP +.B set \f[I]rule\f[R] +Set a rule in the USB Policy as described by \f[I]rule\f[R]. +.TP +.B remove \f[I]num\f[R] +Remove rule number \f[I]num\f[R] from the USB policy. +.SS net +.PP +Used to manage the configuration for network instances. +.TP +.B list +List all network instances defined for the system. +.TP +.B create \f[I]id\f[R] \f[I]uuid\f[R] \f[I]mac\f[R] +Create a new network instance configured as follows, +.PP +\ \ \ \ \ \ \ \f[I]id\f[R]: network identifier +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \f[I]uuid\f[R]: UUID of the backing domain for the network +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \f[I]mac\f[R]: MAC address for the network bridge +.TP +.B mac_addr \f[I]obj\f[R] +Retrieve the MAC address for the network as identified by network object +\f[I]obj\f[R]. +.SH NOTES +.PP +The sync\-cmd functions by communicating with various system daemons +using DBus over Argo. +All DBus messages entering the control domain come through the +rpc\-proxy firewall. +The rpc\-proxy firewall provides a means to filter messages based on +source, destination, interface and member being invoked. +A portion of sync\-cmd functionality requires additional rpc\-proxy +firewall rules beyond those included in a vanilla build of OpenXT. +.SS Net Command Rules +.PP +To enable functionality of the \f[B]net\f[R] command, rules to allow the +following are required: +.IP +.nf +\f[C] +allow dom\-type syncvm destination com.citrix.xenclient.networkdaemon interface org.freedesktop.DBus.Introspectable member Introspect +allow dom\-type syncvm destination com.citrix.xenclient.networkdaemon interface com.citrix.xenclient.networkdaemon member list +allow dom\-type syncvm destination com.citrix.xenclient.networkdaemon interface com.citrix.xenclient.networkdaemon member create_network +\f[R] +.fi +.SS USB Command Rules +.PP +To enable functionality of the \f[B]usb\f[R] command, rules to allow the +following are required: +.IP +.nf +\f[C] +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface org.freedesktop.DBus.Introspectable member Introspect +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_list +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_get_rules +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule_basic +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule_advanced +allow dom\-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_remove_rule +\f[R] +.fi +.SH BUGS +.PP +See GitHub Issues: +.SH AUTHOR +.PP +OpenXT Developers +.SH SEE ALSO +.PP +\f[B]sync\-cmd(1)\f[R] diff --git a/doc/sync-cmd.1.md b/doc/sync-cmd.1.md new file mode 100644 index 0000000..b814b6c --- /dev/null +++ b/doc/sync-cmd.1.md @@ -0,0 +1,192 @@ +% SYNC-CMD(1) Version 1.0 | Synchronizer Command Shell + +NAME +==== + +**sync-cmd** — Command shell for administrating an OpenXT system. + +SYNOPSIS +======== + +**sync-cmd** \[**command** [***arguments***]] + +DESCRIPTION +=========== + +Provides a command shell with an acceptable level of remote administrative +capabilities. + +BUILTIN COMMANDS +================= + +xenmgr +------ + +Used to interact and manage xenmgr process. + +release +: Print the OpenXT release information for the current running software. + +config +: Provides two subcommands to interact with xenmgr config. + +| ***subcommands:*** +| +| get _property_ +| Retrieves _property_ from xenmgr config. +| +| set _property_ _value_ +| Stores _value_ in _property_ of xenmgr config. + +vms +: List all VMs on the system. + +create_vm _template name_ [_json file_] +: Create a VM using the specified template and populate its config using the +optional JSON file. + +delete_vm _identifier_ +: Delete a VM identified by identifier, where identifier may be the UUID or +the name of the VM. + +upgrade _URL_ +: Initiate a platform upgrade using the OTA file located at _URL_. + +reboot +: Reboot the system. + +shutdown +: Shutdown the system. + +upgrade +------- + +Alias to **xenmgr upgrade** + +vm [_identifier_] +-- + +Used to interact and manage VM instances. + +select [_identifier_] +: In interactive mode, this selects the VM to act upon for subsequent commands. + +domstore +: Provides two subcommands to configure a domains domstore. + +| ***subcommands:*** +| +| get _key_ +| Retrieves _key_ from domstore. +| +| set _key_ _value_ +| Stores _value_ for _key_ in domstore. + +argo_firewall +: Provides three subcommands to configure a domains argo firewall. + +| ***subcommands:*** +| +| list +| Retrieves all the firewall rules. +| +| add _rule_ +| Add _rule_ to the firewall. +| +| delete _rule_ +| If _rule_ matches an existing rule, delete it. + +disks +: List all disks associated with the VM. + +disk +: Provides subcommands to manage a disk associated with the VM. + +| ***subcommands:*** +| +| replace _URL_ +| Replace the backing disk image with one downloaded from _URL_. + +usb +--- + +Used to manage the USB policy. + +list +: List all the rules in the USB policy. + +show _num_ | _all_ +: Display _num_ rule in the USB policy, _all_ will display all rules. + +set _rule_ +: Set a rule in the USB Policy as described by _rule_. + +remove _num_ +: Remove rule number _num_ from the USB policy. + +net +--- + +Used to manage the configuration for network instances. + +list +: List all network instances defined for the system. + +create _id_ _uuid_ _mac_ +: Create a new network instance configured as follows, + +| _id_: network identifier +| _uuid_: UUID of the backing domain for the network +| _mac_: MAC address for the network bridge + +mac_addr _obj_ +: Retrieve the MAC address for the network as identified by network object _obj_. + +NOTES +===== + +The sync-cmd functions by communicating with various system daemons using DBus over Argo. All DBus messages entering +the control domain come through the rpc-proxy firewall. The rpc-proxy firewall provides a means to filter messages +based on source, destination, interface and member being invoked. A portion of sync-cmd functionality requires additional +rpc-proxy firewall rules beyond those included in a vanilla build of OpenXT. + +Net Command Rules +----------------- + +To enable functionality of the **net** command, rules to allow the following are required: + +``` +allow dom-type syncvm destination com.citrix.xenclient.networkdaemon interface org.freedesktop.DBus.Introspectable member Introspect +allow dom-type syncvm destination com.citrix.xenclient.networkdaemon interface com.citrix.xenclient.networkdaemon member list +allow dom-type syncvm destination com.citrix.xenclient.networkdaemon interface com.citrix.xenclient.networkdaemon member create_network +``` + +USB Command Rules +----------------- + +To enable functionality of the **usb** command, rules to allow the following are required: + +``` +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface org.freedesktop.DBus.Introspectable member Introspect +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_list +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_get_rules +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule_basic +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_set_rule_advanced +allow dom-type syncvm destination com.citrix.xenclient.usbdaemon interface com.citrix.xenclient.usbdaemon member policy_remove_rule +``` + +BUGS +==== + +See GitHub Issues: + +AUTHOR +====== + +OpenXT Developers + +SEE ALSO +======== + +**sync-cmd(1)**