diff --git a/docs/installation.md b/docs/installation.md index 806da4f2073..90b06654319 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,12 +1,13 @@ + # Installation -SSH on your XenServer, and execute this: +SSH to your XenServer and execute the following: ``` bash -c "$(curl -s http://xoa.io/deploy)" ``` -This will automatically download/import/start the XOA appliance. Nothing is changed on your XenServer itself, it's 100% safe. +This will automatically download/import/start the XOA appliance. Nothing is changed on your XenServer host itself, it's 100% safe. ## [More on XOA](xoa.md) diff --git a/docs/logs.md b/docs/logs.md index a7dce57eccd..b18d181ab51 100644 --- a/docs/logs.md +++ b/docs/logs.md @@ -1,6 +1,7 @@ + # Logs -This section will explain how to check the XOA logs, and be able to detect issues. +This section will explain how to check the XOA logs, and use them to detect issues. ## From the web interface @@ -8,9 +9,9 @@ Go into Settings/Logs view. ## CLI -All XOA logs are stored in `/var/log/syslog`. +All XOA logs are stored in `/var/log/syslog` (on the XO Appliance). -To filter only on what you need, you can use `journalctl`. Let's see some example to filter only logs for `xo-server`: +To filter only what you need, you can use `journalctl`. Below is an example to filter only logs for `xo-server`: ``` $ journalctl -u xo-server -f -n 50 diff --git a/docs/others.md b/docs/others.md index 08c2e2a66f8..7f5a7f93aba 100644 --- a/docs/others.md +++ b/docs/others.md @@ -1,15 +1,16 @@ + # Others We already have other modules in place, e.g for authentication, like a LDAP, SAML, Google or GitHub as external providers. -If you want to understand how modules work, get a look there: +If you want to understand how modules work, have a look here: * [LDAP plugin](/~https://github.com/vatesfr/xen-orchestra/tree/master/packages/xo-server-auth-ldap) * [GitHub authentication](/~https://github.com/vatesfr/xen-orchestra/tree/master/packages/xo-server-auth-github) XO's API can be explored through the `xo-cli` client (please refer to the previous section for details). -There is modules for a lot of various tasks, like: +There are modules for a lot of various tasks, like: * performance analysis * reporting diff --git a/docs/plugins.md b/docs/plugins.md index 9d19b177534..8c706948a56 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -1,12 +1,13 @@ + # Plugins -Xen Orchestra plugins allow to extend features without rewriting the core of the application. +Xen Orchestra plugins allow you to extend features without rewriting the core of the application. -You can see your installed plugins in "Settings" then "Plugins" page: +You can see your installed plugins in "Settings" then the "Plugins" page: ![](./assets/xo5pluginsmenu.png) -Every plugin configuration should be done in the web interface: +All plugin configuration should be done in the web interface: ![](./assets/xo5pluginspage.png) diff --git a/docs/trial_activation.md b/docs/trial_activation.md index 2a78360b12d..682bd9b5f0b 100644 --- a/docs/trial_activation.md +++ b/docs/trial_activation.md @@ -1,28 +1,29 @@ + # Trial activation -Trial will allow you to test all available features in XOA, for 15 days. +A trial will allow you to test all available features in XOA, for 15 days. -The procedure is really simple: +The procedure is very simple: -* register and download a Free Edition [on our website](https://xen-orchestra.com/#/member) +* register, then download a Free Edition [on our website](https://xen-orchestra.com/#/member) * [deploy the virtual appliance](xoa.md) -* activate the Trial via the "Update" view (details below) +* activate the trial via the "Update" view (details below) ## Activate the trial -In your current Free XOA, go register it in the "Updates" view in the main menu: +In your current Free XOA, register it in the "Updates" view in the main menu: ![](./assets/xo5updatemenu.png) -**To register, please use your email/password from your previous registration on xen-orchestra.com**: +**To register your appliance, please use your email/password from your previous registration on xen-orchestra.com**: ![](./assets/xo5register.png) -There, you can click on "Start Trial" green button: +Then you can click on "Start Trial", the green button: ![](./assets/xo5starttrial.png) -Remember to click on Upgrade button after requesting the trial, to download the **Premium Edition** for 15 days! +Remember to click on the Upgrade button after requesting a trial - this will download the **Premium Edition** for 15 days! ![](./assets/xo5updatebutton.png) @@ -32,4 +33,4 @@ In this update view, you can see when your trial will end: ![](./assets/xo5trialend.png) -> **Don't worry! XOA will still work after the trial: you'll be forced to downgrade to Free version, but you won't lose any configuration.** +> **Don't worry! XOA will still work after the trial: you'll be forced to downgrade to Free version, but you won't lose any configuration data.** diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d5caa64a8fa..da0a29f9e70 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,26 +1,27 @@ + # Troubleshooting -This page recap the possible actions to perform if you have any problems with your XOA. +This page recaps the actions you can perform if you have any problems with your XOA. ## XOA deploy error > Auto deploy failed. - No SR specified and Pool default SR is null -It means you don't have a default SR set on the pool you are importing XOA to. To set a default SR, you must first find the SR UUID you want, with `xe sr-list`. When you got the UUID, you can set the default SR with: `xe pool-param-set default-SR=`. When this is done, re-enter the deploy script command and it will work! +It means you don't have a default SR set on the pool you are importing XOA to. To set a default SR, you must first find the SR UUID you want, with `xe sr-list`. When you have the UUID, you can set the default SR with: `xe pool-param-set default-SR=`. When this is done, re-enter the deploy script command and it will work! ## XOA unreachable after boot -XOA is using HVM mode. If your physical host doesn't support virtualization extensions, XOA won't work. To check if your XenServer support hardware assisted virtualization (HVM), you can enter this command in your host: `grep --color vmx /proc/cpuinfo`. If you don't have any result, it means XOA won't work on this hardware. +XOA uses HVM mode. If your physical host doesn't support virtualization extensions, XOA won't work. To check if your XenServer supports hardware assisted virtualization (HVM), you can enter this command in your host: `grep --color vmx /proc/cpuinfo`. If you don't have any result, it means XOA won't work on this hardware. ## Empty page after login -This is happening when your anti-virus or firewall is blocking websocket protocol. This is what we use to communicate between `xo-server` and `xo-web` (see the [architecture page](architecture.md)). +This happens when your antivirus or firewall is blocking the websocket protocol. This is what we use to communicate between `xo-server` and `xo-web` (see the [architecture page](architecture.md)). -The solution is to use **HTTPS**. In this way, websockets will be encapsulated in the secured protocol, avoiding interception from your firewalls or anti-virus system. +The solution is to use **HTTPS**. When doing so, websockets will be encapsulated in the secured protocol, avoiding interception from your firewall or antivirus system. ## XOA migration issues -By default, XOA got a static max memory set to 16GiB. Sometimes, you can have trouble to migrate with this error message: +By default, XOA has a static max memory set to 16GiB. Sometimes you can have trouble migrating with this error message: ``` "Failed","Migrating VM 'XOA' from '' to '' @@ -32,16 +33,16 @@ In this case, it means you need to reduce the static max memory field to a lower ## XOA boot issues -XOA is configured in HVM. It means you need a hardware that support HVM instructions (almost all hardware since 2011). If it's not the case, the symptom is this one: +XOA is configured in HVM. It means you need hardware that supports HVM instructions (almost all hardware since 2011). If that's not the case, the symptom is this: 1. XOA VM starts for few seconds -2. Then shutdown itself +2. Then it shuts down Please check that you have enabled virtualization settings in your BIOS or upgrade your hardware. ## XOA configuration -XOA is a virtual appliance running Debian and Xen Orchestra. If you have any problem, the first thing to do is to use our check service by running the `xoa check` command in a terminal: +XOA is a virtual appliance running Debian with Xen Orchestra installed. If you have any problems, the first thing to do is to use our check service by running the `xoa check` command in a terminal: ``` $ xoa check @@ -58,9 +59,9 @@ If you have something completely different than that, or error messages, lost pa ### Network issues -You can see your current network configuration with a `ifconfig eth0`. If you have an external firewall, please check that you allow the XOA's IP. +You can see your current network configuration by running `ifconfig eth0`. If you have an external firewall, please check that you allow the XOA's IP. -You can modify the IP configuration with `xoa network static` (for a static IP address) or ` xoa network dhcp` to be in DHCP. +You can modify the IP configuration with `xoa network static` (for a static IP address) or ` xoa network dhcp` to use DHCP. ### Memory @@ -82,7 +83,7 @@ FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memo 1: node::Abort() [node] ``` -In that case you need to do to increase the allocated memory to the +In that case, you need to increase the memory allocated to the XOA VM (from 2GB to 4 or 8 GB), and then update the service file (`/etc/systemd/system/xo-server.service`) to increase the allocated memory to xo-server itself: @@ -109,7 +110,7 @@ Then, restart the updater with `systemctl restart xoa-updater`. If the provided certificate is expired, you may want to create a new one. -Connect to your appliance via SSH as root, and execute these commands: +Connect to your appliance via SSH, then as root execute these commands: ``` $ cd /etc/ssl @@ -121,7 +122,7 @@ $ systemctl restart xo-server.service ## XO configuration -The system logs are visible thanks to this command: +The system logs are visible by using this command: ``` $ tail -f /var/log/syslog @@ -131,17 +132,16 @@ You can read more about logs [in the dedicated chapter](logs.md). ### Ghost tasks -If you have ghost tasks accumulating on your XenOrchestra you can try -the following actions in order: +If you have ghost tasks accumulating in your XenOrchestra you can try the following actions in order: 1. refresh the web page -1. disconnect and reconnect the Xen pool/server of the tasks +1. disconnect and reconnect the Xen pool/server owning the tasks 1. restart the XenAPI Toolstack of the XenServer master 1. restart xo-server ### Redownload and rebuild all the packages -If a package disappear due to a build problem or a human error, you can redownload them using the updater: +If a package disappears due to a build problem or human error, you can redownload them using the updater: 1. `rm /var/lib/xoa-updater/update.json` 2. `xoa-updater --upgrade` diff --git a/docs/updater.md b/docs/updater.md index ed5d2a11a0f..bc432815dae 100644 --- a/docs/updater.md +++ b/docs/updater.md @@ -1,10 +1,11 @@ + # Updater -The updater is the central piece to get your XOA on the latest bits of Xen Orchestra. +The updater is the central piece that keeps your XO Appliance running the latest Xen Orchestra code. -It allows also to transform your current version in any others (Trial, Starter, Enterprise or Premium) **without downloading a new XOA**. +It also allows you to change your current version into another (Trial, Starter, Enterprise or Premium) **without downloading a new XOA**. -> By design, the updater is only available in XOA. If you are using the XO from the sources, you'll have to use `git` commands and rebuild to keep up. +> By design, the updater is only available in XOA. If you are using XO from the sources, you'll have to use `git` commands and rebuild to keep up. ## Requirements @@ -12,7 +13,7 @@ In order to work, the updater needs access to `xen-orchestra.com` (port 443). ## Usage -The updater is configurable directly in the web interface, or via the CLI. +The updater is configurable directly from the web interface, or via the CLI. ### From the web interface @@ -20,13 +21,13 @@ The updater is available in the "Update" menu: ![](./assets/xo5updatemenu.png) -You can see the yellow bell icon: it means your appliance is not registered. You **must register in order to have updates and trial**. +You can see the yellow bell icon: it means your appliance is not registered. You **must register in order to have updates and a trial**. ![](./assets/xo5updatetooltip.png) #### Register -Updates and trial will be available as soon as you registered your appliance. To register, use your https://xen-orchestra.com credentials you gave to download it previously (your email and your password): +Updates and trials will be available as soon as you register your appliance. To register, use your https://xen-orchestra.com credentials you gave to download it previously (your email and your password): ![](./assets/xo5register.png) @@ -54,7 +55,7 @@ If you are behind a proxy, you can edit your proxy settings in this panel: ### From the CLI -If you interface is not accessible, or you just prefer to use CLIs commands, it's totally possible to do all the operations. You need to access your XOA by SSH (remember the default credentials: root/xoa. Change them ASAP). +If your interface is not accessible, or you just prefer to use CLIs commands, it's still possible to perform the same steps. You need to access your XOA via SSH (remember the default credentials: xoa/xoa. Change them ASAP). #### Register @@ -102,7 +103,7 @@ Installing new packages... If your updater is down, you can restart it with `systemctl restart xoa-updater`. -If you can't fetch updates, perform some checks from your XOA: +If you can't fetch updates, perform a few checks from your XOA: * you should be able to successfully `ping xen-orchestra.com` * if not, check your `/etc/resolv.conf` file and modify it if necessary (give a correct DNS server) diff --git a/docs/xo-cli.md b/docs/xo-cli.md index adbc5172f88..351fad0ce85 100644 --- a/docs/xo-cli.md +++ b/docs/xo-cli.md @@ -1,8 +1,9 @@ + # xo-cli -This is another client of `xo-server`, this time in command line. +This is another client of `xo-server` - this time in command line form. -Thanks to introspection, `xo-cli` will detect all the available features exposed in `xo-server` API. +Thanks to introspection, `xo-cli` will detect all the available features exposed in the `xo-server` API. ## Usage @@ -53,7 +54,7 @@ Prints all objects: > xo-cli --list-objects ``` -It is possible to filter on object properties, for instance to prints +It is possible to filter on object properties, for instance to print all VM templates: ``` @@ -87,7 +88,7 @@ E.g., adding a new server: The return value is the identifier of this new server in XO. Parameters (except `true` and `false` which are correctly parsed as -booleans) are assumed to be strings, for other types, you may use JSON +booleans) are assumed to be strings. For other types, you may use JSON encoding by prefixing with `json:`: ``` diff --git a/docs/xo-web.md b/docs/xo-web.md index 888472ff6c0..100531f3101 100644 --- a/docs/xo-web.md +++ b/docs/xo-web.md @@ -1,6 +1,7 @@ + # xo-web -This is probably the first thing you'll see of Xen Orchestra. The Web interface allows to interact with your virtual infrastructure. As a module for XO-web, it facilitates the everyday Xen administrator work, but also provide a solution to delegate some part of your infrastructure to other people. +This is probably the first part of Xen Orchestra you'll see. The Web interface allows you to interact with your virtual infrastructure. As a module of XO-Web it facilitates everyday Xen administrator work, but also provides a solution to delegate parts of your infrastructure to other people. ![](https://xen-orchestra.com/blog/content/images/2015/05/tablet3-1.JPG) diff --git a/docs/xoa.md b/docs/xoa.md index 089f5ba1ee0..0293435ec31 100644 --- a/docs/xoa.md +++ b/docs/xoa.md @@ -1,12 +1,13 @@ + # XOA -The fastest way to install Xen Orchestra is to use our Appliance. You can deploy it by connecting into your XenServer and execute this: +The fastest way to install Xen Orchestra is to use our Appliance. You can deploy it by connecting to your XenServer host and executing this: ``` bash -c "$(curl -s http://xoa.io/deploy)" ``` -> This won't write or modify anything into your XenServer system: it will just import XOA VM in your default storage repository. +> This won't write or modify anything on your XenServer host: it will just import the XOA VM into your default storage repository. XOA is a Debian VM with: @@ -24,50 +25,50 @@ By default, this VM is configured with: * 2GB of RAM * 15GB of disk (10GB for `/` and 5GB for `/var`) -For usage on huge infrastructure (more than 500+ VMs), feel free to raise the RAM. +For usage on huge infrastructure (more than 500+ VMs), feel free to increase the RAM. ## Deployment ### The quickest way -SSH on your XenServer, and execute this: +SSH to your XenServer, and execute the following: ``` bash -c "$(curl -s http://xoa.io/deploy)" ``` -And follow the instructions: +Then follow the instructions: -* Your IP configuration will be requested: it's in **DHCP by default**, otherwise you can enter a fixed IP address (eg `192.168.0.10`) -* If DHCP is selected, the script will continue automatically. Otherwise, a netmask, gateway and DNS should be provided. +* Your IP configuration will be requested: it's set to **DHCP by default**, otherwise you can enter a fixed IP address (eg `192.168.0.10`) +* If DHCP is selected, the script will continue automatically. Otherwise a netmask, gateway, and DNS should be provided. * XOA will be deployed on your default storage repository. You can move it elsewhere anytime after. ### The alternative -Download XOA on xen-orchestra.com. Once you've got the XVA file, you can import it with `xe vm-import filename=xoa_unified.xva` or via XenCenter. +Download XOA from xen-orchestra.com. Once you've got the XVA file, you can import it with `xe vm-import filename=xoa_unified.xva` or via XenCenter. -After the VM is imported, you just need to start it with a `xe vm-start vm="XOA Unified"` or with XenCenter. +After the VM is imported, you just need to start it with `xe vm-start vm="XOA Unified"` or with XenCenter. ## Registration -**The first thing** you need to do with your XOA, is to register. [Read the documentation on the page dedicated to the updater/register inferface](updater.md). +**The first thing** you need to do with your XOA is register. [Read the documentation on the page dedicated to the updater/register inferface](updater.md). ### First console connection -If you connect in SSH or via console, the default credentials are: +If you connect via SSH or console, the default credentials are: * user: xoa * password: xoa During your first connection, the system will ask you to: -* enter again the current password (`xoa`) +* enter the current password again (`xoa`) * enter your new password * retype your new password When it's done, you'll be disconnected, so reconnect again with your new password. -Here is an example when you connect in SSH for the first time: +Here is an example when you connect via SSH for the first time: ``` $ ssh xoa@192.168.100.146 @@ -128,7 +129,7 @@ Administrator. It usually boils down to these three things: ### Network configuration -XOA is in **DHCP** by default, so if you need to configure the IP address, please run the command `xoa network static`. It will ask you network details: +XOA uses **DHCP** by default, so if you need to configure the IP address, please run the command `xoa network static`. It will ask you network details: ``` $ xoa network static @@ -142,11 +143,11 @@ Xen Orchestra is now accessible in your browser on ` https://your-vm-ip`. You can access the VM console through XenCenter or using VNC through a SSH tunnel. -If you want to go back in DHCP, just use `xoa network dhcp` +If you want to go back in DHCP, just run `xoa network dhcp` ### SSH Pro Support -By default, if you need support, there is a dedicated user named `xoa-support`. We are the only one with the private key. If you want our assistance on your XOA, you can open a private tunnel: +By default, if you need support, there is a dedicated user named `xoa-support`. We are the only one with the private key. If you want our assistance on your XOA, you can open a private tunnel with the command `xoa support tunnel` like below: ``` $ xoa support tunnel @@ -156,13 +157,13 @@ Do not stop this command before the intervention is over! Give this id to the support: 40713 ``` -Give us this number, we'll be able to access your XOA in a secure manner. Then, close the tunnel with `Ctrl+C` after the support fixed your issue. +Give us this number, we'll be able to access your XOA in a secure manner. Then, close the tunnel with `Ctrl+C` after your issue has been solved by support. > If you want to deactivate this bundled user, you can type `chage -E 0 xoa-support`. To re-activate this account, you must use the `chage -E 1 xoa-support`. ### Firewall -By default, XOA is firewalled, with only ports 22, 80 and 443 opened. You can see the current status of the firewall using `sudo ufw status verbose` command: +By default XOA is firewalled, with only ports 22, 80 and 443 opened. You can see the current status of the firewall using the `sudo ufw status verbose` command: ``` Status: active @@ -194,13 +195,13 @@ In any case, if you lose your password, you can reset the database and get the d ## Timezone -You can verify if your time is correctly set with the `date` command. To set XOA to your current timezone, use `sudo dpkg-reconfigure tzdata`. +You can verify that your time is correctly set with the `date` command. To set XOA to your current timezone, use `sudo dpkg-reconfigure tzdata`. ## Restart the service -You can restart Xen Orchestra by going in XOA on SSH (or console) and type `systemctl restart xo-server.service`. +You can restart Xen Orchestra by accessing XOA via SSH (or console) and running `systemctl restart xo-server.service`. -To check the status of `xo-server`, use `systemctl status xo-server.service`, it should display something like that: +To check the status of `xo-server`, use `systemctl status xo-server.service`, it should display something like this: ``` xo-server.service - XO Server @@ -217,13 +218,13 @@ Aug 14 10:59:48 xoa xo-server[394]: WebServer listening on http://0.0.0.0:80 ## Migrate from an older XOA -If you still use the first XOA (which is not the "unified" version), you could migrate easily all your settings (ACLs, users, server, etc.) to the new one painlessly. +If you still use the first XOA (which was not the "unified" version), you can easily migrate all your settings (ACLs, users, servers, etc) to the new version painlessly. -To do that, go into "Settings/Config" of your old XOA. Export the configuration: you'll download a `config.json` file. +To do so, go into "Settings/Config" of your old XOA. Export the configuration: you'll download a `config.json` file. ![](./assets/xo5_export.png) -Now, go to your new unified XOA, "Settings/Config" and import the `config.json` file you downloaded previously, by doing a drag and drop: +Now go to your new unified XOA, "Settings/Config" and import the `config.json` file you downloaded previously, by doing a drag and drop: ![](./assets/xo5_import.png)