Skip to content

Commit cd30faf

Browse files
olivierlambertolivierlambert
committed
add doc
1 parent e3f248c commit cd30faf

33 files changed

+4490
-0
lines changed

‎docs/.vuepress/config.js

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
module.exports = {
2+
themeConfig: {
3+
smoothScroll: true,
4+
logo: 'https://xcp-ng.org/assets/img/smalllogo.png',
5+
lastUpdated: 'Last Updated', // add latest Git commit modification for each file
6+
repo: 'xcp-ng/xcp', // point to the GH repo
7+
editLinks: true, // display link for people to edit a page
8+
editLinkText: 'Help us to improve this page!', // link text
9+
docsDir: 'docs',
10+
nav: [
11+
{ text: 'Home', link: 'https://xcp-ng.org' },
12+
{ text: 'News', link: 'https://xcp-ng.org/news' },
13+
{ text: 'Pro Support', link: 'https://xcp-ng.com' },
14+
{ text: 'Documentation', link: '/' }
15+
],
16+
sidebar: [
17+
{
18+
title: 'XCP-ng Documentation', // required
19+
path: '/', // optional, link of the title, which should be an absolute path and must exist
20+
collapsable: false, // optional, defaults to true
21+
sidebarDepth: 1, // optional, defaults to 1
22+
children: [
23+
['/releases', 'Releases'],
24+
['/requirements', 'Requirements'],
25+
['/hcl', 'Hardware compatibility list'],
26+
['/install', 'Installation'],
27+
['/upgrade', 'Upgrade'],
28+
['/updates', 'Updates'],
29+
['/additionalpackages', 'Extra packages'],
30+
['/storage', 'Storage'],
31+
['/networking', 'Networking'],
32+
['/compute', 'Compute'],
33+
['/api', 'API'],
34+
['/troubleshooting', 'Troubleshooting'],
35+
]
36+
},
37+
{
38+
title: 'Management & Backup', // required
39+
path: '/manage', // optional, link of the title, which should be an absolute path and must exist
40+
collapsable: false, // optional, defaults to true
41+
sidebarDepth: 1, // optional, defaults to 1
42+
children: [
43+
['/management', 'Management'],
44+
['/backup', 'Backup'],
45+
['/cloud', 'Cloud'],
46+
['/hosting', 'Hosting'],
47+
]
48+
},
49+
{
50+
title: 'Project', // required
51+
path: '/project', // optional, link of the title, which should be an absolute path and must exist
52+
collapsable: false, // optional, defaults to true
53+
sidebarDepth: 1, // optional, defaults to 1
54+
children: [
55+
['/contributing', 'Contributing'],
56+
['/develprocess.md', 'Developement Process'],
57+
['/licenses', 'Licenses'],
58+
['/gitrepo', 'Git Repositories'],
59+
['/mirrors', 'Mirrors'],
60+
['/roadmap', 'Roadmap'],
61+
['/glossary', 'Glossary'],
62+
]
63+
},
64+
]
65+
}
66+
}

‎docs/.vuepress/dist/manifest/server.json

+2,025
Large diffs are not rendered by default.

‎docs/.vuepress/styles/palette.styl

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
$accentColor = #cc584c

‎docs/README.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# XCP-ng documentation
2+
3+
XCP-ng is a high performance enterprise level virtualization platform with a rich ecosystem.
4+
5+
Based on XenServer, it's the result of massive cooperation between individuals and companies, to deliver a product without limits. No restrictions on features and every bit available on GitHub!
6+
7+
Visit the main website to know more: [https://xcp-ng.org](https://xcp-ng.org)
8+
9+
![](https://xcp-ng.org/assets/img/mainlogo.png)
10+

‎docs/additionalpackages.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Additional packages
2+
3+
The controller domain (dom0) is a privileged linux VM, based on CentOS.
4+
5+
It may be useful to add more packages to it, with precaution. The XCP-ng project offers some in its repositories, and other packages can be installed from CentOS, EPEL, or even third party repositories.
6+
7+
## Rules
8+
9+
### 1. Never enable additional repositories
10+
11+
The [update process](https://github.com/xcp-ng/xcp/wiki/Updates-Howto) for XCP-ng assumes that **only XCP-ng repositories are enabled**. If you enable more repositories, updates may get pulled from there and overwrite XCP-ng packages and thus **break your system**.
12+
13+
**Warning**: some third party repositories are auto-enabled when installed. This is the case of EPEL, for example. Installing `epel-release` (the common way to enable it on CentOS) will automatically enable it. To solve this, EPEL repositories are added at system installation since XCP-ng 8.0, but they are *disabled*.
14+
15+
*But then, how to install from such additional repositories?*
16+
17+
You simply need to learn `yum`'s `--enablerepo` switch. Very handy, it enables one or more repositories **only for the current execution of the command**, without enabling the repo system-wide.
18+
19+
See section *How to install* below for practical details.
20+
21+
To disable a repository, edit `/etc/yum.repos.d/name_of_repo.repo` and set `enabled=0` where the value is `1`.
22+
23+
### 2. Prefer additional packages from XCP-ng's own repositories
24+
25+
We offer a number of additional packages ranging from [ZFS support](https://github.com/xcp-ng/xcp/wiki/ZFS-on-XCP-ng), [newer drivers](https://github.com/xcp-ng/xcp/wiki/Kernel-modules-policy#how-to-use-alternate-or-additional-modules) or [newer kernel](https://github.com/xcp-ng/xcp/wiki/Alternate-kernel), to small utilities such as `vim`, `joe`, `iperf`, `mc`, etc.
26+
27+
A list of such utilities is available at https://github.com/xcp-ng/xcp/issues/56#issuecomment-480337976. It is a wishlist from the community. The "action" column will tell you if the utility is available in XCP-ng repositories.
28+
29+
Packages installed from our repositories are:
30+
* tested
31+
* maintained (security/bugfix updates)
32+
33+
:::warning
34+
Anything installed from outside XCP-ng repositories is at your own risk
35+
:::
36+
37+
### 3. Do not overwrite existing packages from the system
38+
39+
Some repositories contain packages that have a higher version number than ours. `yum` will tend to want to install them over our packages. Always check that it is not trying to overwrite on of our packages.
40+
41+
### 4. Keep your dom0 minimal
42+
43+
The controller domain is not an all-purpose linux system. It must remain minimal to do what it is meant to do efficiently.
44+
* Avoid bloat (do not attempt to transform it into a linux workstation. Use a VM instead.)
45+
* Avoid CPU or RAM-intensive programs
46+
* Avoid software that pulls in many dependencies
47+
* Avoid any software that may interfere with the existing
48+
49+
### 5. Ask before
50+
51+
If you have [pro support](https://xcp-ng.com), ask there. As part of the support, additional supported packages may be provided. Else ask the community on the [forum](https://xcp-ng.org/forum/).
52+
53+
## How to install
54+
55+
Before doing any change, start keeping track somewhere of any change you bring to the system. This will help for:
56+
* support
57+
* knowing what packages you need to update regularly for security fixes or bugfixes
58+
* reinstalling them after a system upgrade via the installation ISO
59+
60+
### From XCP-ng repositories
61+
62+
`yum install name_of_package`
63+
64+
### From CentOS repositories
65+
66+
The CentOS repos are already installed but are disabled, on purpose. Install from them with:
67+
```
68+
yum install name_of_package --enablerepo=base,updates
69+
```
70+
71+
Make sure it will not try to overwrite system packages with updates from CentOS. XCP-ng uses fixed or modified versions of some CentOS packages whereas the CentOS repos point at the latest.
72+
73+
### From EPEL repositories
74+
75+
On XCP-ng 8.0, the EPEL repos are already installed but are disabled, on purpose. Install from them with:
76+
```
77+
yum install name_of_package --enablerepo=epel
78+
```
79+
80+
Sometimes you'll need extra dependencies from CentOS. Replace the command with:
81+
```
82+
yum install name_of_package --enablerepo=epel,base,updates
83+
```
84+
85+
And as above make sure no package from the system will get overwritten in the process.
86+
87+
On XCP-ng 7.6:
88+
* `yum install epel-release --enablerepo=extras`
89+
* then edit `/etc/yum.repos.d/epel.repo` and set `enabled=0`
90+
* then `yum install name_of_package --enablerepo=epel`
91+
92+
### From other third party repositories
93+
94+
1. Avoid that if possible
95+
2. Be extra cautious
96+
3. After installing the repository, disable it right away (`enabled=0` in repo file)
97+
4. install packages with: `yum install name_of_package --enablerepo=name_of_repo`
98+
99+
And as usual make sure it won't overwrite existing packages...
100+
101+
## Up to date additional packages
102+
103+
If you installed from XCP-ng repositories, [they will be updated like the rest of the XCP-ng system](updates.md).
104+
105+
If you installed from any other repository, including CentOS and EPEL, you need to update them (and their dependencies) manually
106+
107+
## System upgrade
108+
109+
See [upgrade section](upgrade.md) for a discussion of the differences between "Installer upgrade" and "`yum`-style upgrade".
110+
111+
Installer upgrade will reinstall the system from scratch and just keep your configuration related to XCP-ng (network, VMs, SRs, etc.). Anything else will have to be re-done.
112+
113+
`yum-style` upgrade will try to update or keep the packages that you installed. Packages installed from XCP-ng repositories should get updated seamlessly. Packages from other repositories will not get updated: they may be left in place (then you'll have to update them yourselves if needed), removed (due to package conflicts or because they are obsoleted by packages from the updated XCP-ng) or even make the upgrade fail until they are manually removed.

‎docs/api.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# API
2+
3+
XCP-ng is using XAPI as main API. This API is used by all clients. For more details go to [XAPI website](https://xapi-project.github.io/).
4+
5+
![](https://xapi-project.github.io/xen-api/classes.png)
6+
7+
:::tip
8+
If you want to build an application on top of XCP-ng, we strongly suggest to use Xen Orchestra API instead of XCP-ng API. Indeed, XO provides an abstraction layer that's really easier to use, and also acts as a central point for your whole infrastructure.
9+
:::
10+
11+
## Architecture
12+
13+
![](https://xapi-project.github.io/getting-started/pool.png)
14+
15+
16+
## Modifications
17+
18+
:::warning
19+
Those changes aren't officially supported, and will be also wiped after an ISO upgrade
20+
:::
21+
22+
### 24h task timeout
23+
24+
Edit the `/etc/xapi.conf` file, and uncomment/change that line:
25+
26+
```
27+
# pending_task_timeout = 86400 # 1 day in seconds
28+
```
29+
30+
To:
31+
32+
33+
```
34+
pending_task_timeout = 172800 # 2 days in seconds
35+
```
36+
37+
Don't forget to restart the toolstack after that with a `xe-toolstack-restart`.

‎docs/backup.md

Whitespace-only changes.

‎docs/cloud.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Cloud features with XCP-ng
2+
3+
You have multiple possibilities:
4+
5+
1. Using Xen Orchestra Cloud features (ACLs, Self Service)
6+
2. Using CloudStack or OpenStack (adapted to very large deployments)
7+
8+
## Xen Orchestra
9+
10+
:::tip
11+
TODO
12+
:::
13+
14+
## CloudStack
15+
16+
At the outset this writeup is an outcome of this XCP-ng forum [discussion](https://xcp-ng.org/forum/topic/1109/xcp-ng-issues-with-cloudstack-4-11-2-with-iscsi-sr/10). Basically, setting up XCP-Ng using XCP-ng Center is very straightforward but to overlay Cloudstack and get them all to work in unison is the tricky part. To provide more background , consider a 2 node XCP-ng 7.6.0 pool setup with iSCSI target running on a different host with all necessary traffic segregation principles applied (guest, storage and management).
17+
18+
### Installation Steps (with tips and tricks)
19+
20+
1. Follow along the Cloudstack Management Server installation [steps](http://docs.cloudstack.apache.org/en/4.11.2.0/installguide/hypervisor/xenserver.html#system-requirements-for-xenserver-hosts).
21+
22+
> Tip #1: if you need iSCSI , when you login to Cloudstack Management UI avoid the "Basic setup" and choose the option "I have used CloudStack before" (the button that is less obvious) since with basic for some reasons forces you into NFS.
23+
But don't proceed with configuring your Cloudstack Management Server just yet.
24+
25+
2. If you have not setup your iSCSI storage on the XCP-ng pool . Please proceed to do it and ensure that they list in XCP-ng Center or Xen Orchestra and ensure everything looks good. So as listed in the Cloudstack Installation guide, we will be using the "Presetup" option to setup Primary ISCSI storage on Cloudstack.
26+
27+
3. Now SSH into the Cloudstack Management host, go to the folder (`/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/`) . This folder contains several useful scripts which comes in handy pick the one that says `setup_heartbeat_sr.sh` and copy that over to the Xen Pool master host and ensure you have executable rights on script file .
28+
29+
4. Before you run the script , run the `lvscan` command which scan for presence of LVM on your pool and produce some result if you had made any undesirable edits to `/etc/lvm/lvm.conf` file this step will most likely fail. If it does , make sure you restore the `lvm.conf` to its original state.
30+
31+
5. Now execute the `setup_heartbeat_sr.sh` with the UUID of the iSCSI SR that you had setup in Step #2. Internally does lvcreate with a bunch of params . Which basically creates a hb-volume (heartbeat volume) for the SR.
32+
33+
6. After this succeeds proceed to setting up your Cloudstack Management host and your infrastructure and that point of adding your primary storage use the "Presetup" option. You'll see that it works without issues.
34+
35+
> Note: At the time of writing this page: Cloudstack 4.12 and XCP-Ng 7.6.0 where the latest versions of the respective software.

‎docs/compute.md

Whitespace-only changes.

‎docs/contributing.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Contributing
2+
3+
There are two ways of contributing:
4+
* by giving some of your time to work on the project (support, documentation, developement...)
5+
* with money, by subscribing to [Pro Support](https://xcp-ng.com/), which funds further developments.
6+
7+
## Helping others
8+
9+
You don't have to be a programmer/IT-nerd to help at this project. Just ask or offer your help:
10+
11+
* Forum: https://xcp-ng.org/forum
12+
* IRC: #xcp-ng and #xcp-ng-dev on irc.freenode.net
13+
14+
We are happy about every helping hand!
15+
16+
## Documentation
17+
18+
Our [Wiki](https://github.com/xcp-ng/xcp/wiki) needs love ❤️ and care ✍️ . Many pages are non existent or not fully filled.
19+
20+
Just start writing things down or add things to existing pages!
21+
22+
Anyone with a github account can edit the wiki.
23+
24+
## Developing
25+
26+
You are a developer and want to code with us? Cool!
27+
28+
* connect to us via
29+
* IRC: #xcp-ng and #xcp-ng-dev on irc.freenode.net
30+
* Forum -> Development Corner: https://xcp-ng.org/forum/category/7/development
31+
* scroll through our [Issues](https://github.com/xcp-ng/xcp/issues) to find your first project 🔨
32+
33+
## Testing
34+
35+
It's important to test XCP-ng on many different platforms and devices. You have gear laying around or access to some special devices? -> be a tester and test all the features of XCP-ng 🚀
36+
37+
Your results are very welcome in our [[Hardware Compatibility List (HCL)]]!
38+
39+
It's also important to test Operating Systems on XCP-ng. You have fun to install different Operating Systems? -> great! Test them all on XCP-ng!
40+
41+
Your results are very welcome in our [List of supported Guest Systems](https://github.com/xcp-ng/xcp/wiki/Guest-System-Support)!
42+
43+
## What does it mean to be a packager?
44+
45+
TODO
46+
47+
## How to become a packager in the XCP-ng project
48+
49+
TODO
50+
51+
## Koji initial setup
52+
53+
See [[Development process tour]] for an introduction about the packaging process and Koji.
54+
55+
### Certificates
56+
Once accepted as a proven packager or as an apprentice, you will receive your connection certificate as well as the server's CA public certificate:
57+
```
58+
client.crt # your certificate
59+
serverca.crt
60+
clientca.crt
61+
```
62+
63+
Copy them to `~/.koji/` (create it if it doesn't exist yet).
64+
Make sure not to lose them and to not let anyone put their hands on them.
65+
66+
You may also receive a browser certificate for the connection to Koji's web interface. It has little use, though. Unless you have admin rights, the only actions available are canceling and resubmitting builds, which you can already do with the `koji` CLI tool.
67+
```
68+
{login}_browser_certificate.p12
69+
```
70+
You need to import it into your web browser's certificate store and then use it when you log in to https://koji.xcp-ng.org/
71+
72+
### Installing koji
73+
If your linux distribution provides `koji` in its repositories (e.g. Fedora, CentOS or Mageia), simply install it from there. Else you can either run it from a container, or clone it from https://pagure.io/koji, then run it from there with something like `PYTHONPATH=$(realpath .):/usr/lib/python3.5/site-packages/ cli/koji help`. If it fails, you probably need to install additional python dependencies.
74+
75+
### Configuring koji
76+
Put this in `~/.koji/config`:
77+
```
78+
[koji]
79+
80+
;url of XMLRPC server
81+
server = https://kojihub.xcp-ng.org
82+
83+
;url of web interface
84+
weburl = http://koji.xcp-ng.org
85+
86+
;url of package download site
87+
topurl = http://koji.xcp-ng.org/kojifiles
88+
89+
;path to the koji top directory
90+
topdir = /mnt/koji
91+
92+
; configuration for SSL authentication
93+
94+
;client certificate
95+
cert = ~/.koji/client.crt
96+
97+
;certificate of the CA that issued the client certificate
98+
ca = ~/.koji/clientca.crt
99+
100+
;certificate of the CA that issued the HTTP server certificate
101+
serverca = ~/.koji/serverca.crt
102+
```
103+
104+
In some cases, we've found that the configuration file in ~/.koji was not used. Solution: `cp ~/.koji /etc/koji.conf`.
105+
106+
### Test your connection
107+
`koji moshimoshi`. If it replies to you (in any language), then your connection to the server works.
108+
109+
### Useful commands
110+
111+
Just a quick list. Make sure to have read and understood [[Development process tour]] and [[RPM Packaging guidelines]].
112+
113+
* Get help about the commands: `koji help` or `koji {command name} --help`.
114+
* Start a build: `koji build [--scratch] {target} {SCM URL}`
115+
* List the builds in a tag: `koji list-tagged {tag name}`

0 commit comments

Comments
 (0)