From 13fd9be5661bd991932e50f85fb5727088c17465 Mon Sep 17 00:00:00 2001 From: Julien Fontanet Date: Thu, 28 May 2020 16:05:33 +0200 Subject: [PATCH] feat(*/README.md): re-generate for all packages --- @vates/read-chunk/README.md | 4 +- @xen-orchestra/async-map/README.md | 29 +-- @xen-orchestra/async-map/USAGE.md | 5 + @xen-orchestra/audit-core/README.md | 28 +++ @xen-orchestra/audit-core/USAGE.md | 0 @xen-orchestra/babel-config/README.md | 18 ++ @xen-orchestra/babel-config/USAGE.md | 0 @xen-orchestra/backups-cli/README.md | 28 +++ @xen-orchestra/backups-cli/USAGE.md | 0 @xen-orchestra/backups/README.md | 28 +++ @xen-orchestra/backups/USAGE.md | 0 @xen-orchestra/cr-seed-cli/README.md | 28 +++ @xen-orchestra/cr-seed-cli/USAGE.md | 0 @xen-orchestra/cron/README.md | 27 +-- @xen-orchestra/cron/USAGE.md | 98 ++++++++ @xen-orchestra/defined/README.md | 31 +-- @xen-orchestra/defined/USAGE.md | 0 @xen-orchestra/emit-async/README.md | 27 +-- @xen-orchestra/emit-async/USAGE.md | 26 +++ @xen-orchestra/fs/README.md | 30 +++ @xen-orchestra/fs/USAGE.md | 0 @xen-orchestra/log/README.md | 27 +-- @xen-orchestra/log/USAGE.md | 122 ++++++++++ @xen-orchestra/mixin/README.md | 31 +-- @xen-orchestra/mixin/USAGE.md | 0 @xen-orchestra/self-signed/README.md | 8 +- @xen-orchestra/self-signed/USAGE.md | 13 ++ @xen-orchestra/template/README.md | 25 +- @xen-orchestra/template/USAGE.md | 19 ++ @xen-orchestra/upload-ova/README.md | 7 +- @xen-orchestra/upload-ova/USAGE.md | 40 ++++ packages/complex-matcher/README.md | 25 +- packages/complex-matcher/USAGE.md | 18 ++ packages/value-matcher/README.md | 27 +-- packages/value-matcher/USAGE.md | 17 ++ packages/vhd-cli/README.md | 31 +-- packages/vhd-cli/USAGE.md | 0 packages/vhd-lib/README.md | 30 +++ packages/vhd-lib/USAGE.md | 0 packages/xapi-explore-sr/README.md | 25 +- packages/xapi-explore-sr/USAGE.md | 4 + packages/xen-api/README.md | 47 ++-- packages/xen-api/USAGE.md | 95 ++++++++ packages/xo-acl-resolver/README.md | 30 +-- packages/xo-acl-resolver/USAGE.md | 29 +++ packages/xo-cli/README.md | 34 +-- packages/xo-cli/USAGE.md | 112 +++++++++ packages/xo-collection/README.md | 25 +- packages/xo-collection/USAGE.md | 217 ++++++++++++++++++ packages/xo-common/README.md | 29 +-- packages/xo-common/USAGE.md | 0 packages/xo-import-servers-csv/README.md | 25 +- packages/xo-import-servers-csv/USAGE.md | 16 ++ packages/xo-lib/README.md | 37 +-- packages/xo-lib/USAGE.md | 116 ++++++++++ packages/xo-remote-parser/README.md | 31 +-- packages/xo-remote-parser/USAGE.md | 0 packages/xo-server-audit/README.md | 33 +-- packages/xo-server-audit/USAGE.md | 2 + packages/xo-server-auth-github/README.md | 34 +-- packages/xo-server-auth-github/USAGE.md | 13 ++ packages/xo-server-auth-google/README.md | 31 +-- packages/xo-server-auth-google/USAGE.md | 29 +++ packages/xo-server-auth-ldap/README.md | 31 +-- packages/xo-server-auth-ldap/USAGE.md | 34 +++ packages/xo-server-auth-saml/README.md | 31 +-- packages/xo-server-auth-saml/USAGE.md | 15 ++ packages/xo-server-backup-reports/README.md | 33 +-- packages/xo-server-backup-reports/USAGE.md | 4 + packages/xo-server-load-balancer/README.md | 32 +-- packages/xo-server-load-balancer/USAGE.md | 2 + packages/xo-server-perf-alert/README.md | 10 +- packages/xo-server-perf-alert/USAGE.md | 2 + packages/xo-server-sdn-controller/README.md | 14 +- packages/xo-server-sdn-controller/USAGE.md | 3 + packages/xo-server-test/README.md | 12 +- packages/xo-server-test/USAGE.md | 149 ++++++++++++ packages/xo-server-transport-email/README.md | 27 +-- packages/xo-server-transport-email/USAGE.md | 2 + .../xo-server-transport-icinga2/README.md | 29 +-- packages/xo-server-transport-icinga2/USAGE.md | 10 + packages/xo-server-transport-nagios/README.md | 29 +-- packages/xo-server-transport-nagios/USAGE.md | 10 + packages/xo-server-transport-slack/README.md | 31 +-- packages/xo-server-transport-slack/USAGE.md | 41 ++++ packages/xo-server-transport-xmpp/README.md | 29 +-- packages/xo-server-transport-xmpp/USAGE.md | 2 + packages/xo-server-usage-report/README.md | 29 +-- packages/xo-server-usage-report/USAGE.md | 2 + packages/xo-server-web-hooks/README.md | 25 +- packages/xo-server-web-hooks/USAGE.md | 2 + packages/xo-vmdk-to-vhd/README.md | 27 +-- packages/xo-vmdk-to-vhd/USAGE.md | 23 ++ scripts/README.md.tpl | 14 +- 94 files changed, 1708 insertions(+), 857 deletions(-) create mode 100644 @xen-orchestra/async-map/USAGE.md create mode 100644 @xen-orchestra/audit-core/README.md create mode 100644 @xen-orchestra/audit-core/USAGE.md create mode 100644 @xen-orchestra/babel-config/README.md create mode 100644 @xen-orchestra/babel-config/USAGE.md create mode 100644 @xen-orchestra/backups-cli/README.md create mode 100644 @xen-orchestra/backups-cli/USAGE.md create mode 100644 @xen-orchestra/backups/README.md create mode 100644 @xen-orchestra/backups/USAGE.md create mode 100644 @xen-orchestra/cr-seed-cli/README.md create mode 100644 @xen-orchestra/cr-seed-cli/USAGE.md create mode 100644 @xen-orchestra/cron/USAGE.md create mode 100644 @xen-orchestra/defined/USAGE.md create mode 100644 @xen-orchestra/emit-async/USAGE.md create mode 100644 @xen-orchestra/fs/README.md create mode 100644 @xen-orchestra/fs/USAGE.md create mode 100644 @xen-orchestra/log/USAGE.md create mode 100644 @xen-orchestra/mixin/USAGE.md create mode 100644 @xen-orchestra/self-signed/USAGE.md create mode 100644 @xen-orchestra/template/USAGE.md create mode 100644 @xen-orchestra/upload-ova/USAGE.md create mode 100644 packages/complex-matcher/USAGE.md create mode 100644 packages/value-matcher/USAGE.md create mode 100644 packages/vhd-cli/USAGE.md create mode 100644 packages/vhd-lib/README.md create mode 100644 packages/vhd-lib/USAGE.md create mode 100644 packages/xapi-explore-sr/USAGE.md create mode 100644 packages/xen-api/USAGE.md create mode 100644 packages/xo-acl-resolver/USAGE.md create mode 100644 packages/xo-cli/USAGE.md create mode 100644 packages/xo-collection/USAGE.md create mode 100644 packages/xo-common/USAGE.md create mode 100644 packages/xo-import-servers-csv/USAGE.md create mode 100644 packages/xo-lib/USAGE.md create mode 100644 packages/xo-remote-parser/USAGE.md create mode 100644 packages/xo-server-audit/USAGE.md create mode 100644 packages/xo-server-auth-github/USAGE.md create mode 100644 packages/xo-server-auth-google/USAGE.md create mode 100644 packages/xo-server-auth-ldap/USAGE.md create mode 100644 packages/xo-server-auth-saml/USAGE.md create mode 100644 packages/xo-server-backup-reports/USAGE.md create mode 100644 packages/xo-server-load-balancer/USAGE.md create mode 100644 packages/xo-server-perf-alert/USAGE.md create mode 100644 packages/xo-server-sdn-controller/USAGE.md create mode 100644 packages/xo-server-test/USAGE.md create mode 100644 packages/xo-server-transport-email/USAGE.md create mode 100644 packages/xo-server-transport-icinga2/USAGE.md create mode 100644 packages/xo-server-transport-nagios/USAGE.md create mode 100644 packages/xo-server-transport-slack/USAGE.md create mode 100644 packages/xo-server-transport-xmpp/USAGE.md create mode 100644 packages/xo-server-usage-report/USAGE.md create mode 100644 packages/xo-server-web-hooks/USAGE.md create mode 100644 packages/xo-vmdk-to-vhd/USAGE.md diff --git a/@vates/read-chunk/README.md b/@vates/read-chunk/README.md index 64453301d..0e43e12b2 100644 --- a/@vates/read-chunk/README.md +++ b/@vates/read-chunk/README.md @@ -2,6 +2,8 @@ # @vates/read-chunk [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/@vates/read-chunk)](https://npmjs.org/package/@vates/read-chunk) ![License](https://badgen.net/npm/license/@vates/read-chunk) [![PackagePhobia](https://badgen.net/packagephobia/install/@vates/read-chunk)](https://packagephobia.now.sh/result?p=@vates/read-chunk) + > Read a chunk of a Node stream ## Install @@ -41,4 +43,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/async-map/README.md b/@xen-orchestra/async-map/README.md index bc38cfdd7..46fc3a819 100644 --- a/@xen-orchestra/async-map/README.md +++ b/@xen-orchestra/async-map/README.md @@ -1,6 +1,10 @@ + + # @xen-orchestra/async-map [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> ${pkg.description} +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/async-map)](https://npmjs.org/package/@xen-orchestra/async-map) ![License](https://badgen.net/npm/license/@xen-orchestra/async-map) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/async-map)](https://packagephobia.now.sh/result?p=@xen-orchestra/async-map) + +> Similar to Promise.all + lodash.map but wait for all promises to be settled ## Install @@ -12,25 +16,10 @@ Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/async ## Usage -**TODO** +```js +import asyncMap from '@xen-orchestra/async-map' -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build +const array = await asyncMap(collection, iteratee) ``` ## Contributions @@ -46,4 +35,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/async-map/USAGE.md b/@xen-orchestra/async-map/USAGE.md new file mode 100644 index 000000000..18cc5d043 --- /dev/null +++ b/@xen-orchestra/async-map/USAGE.md @@ -0,0 +1,5 @@ +```js +import asyncMap from '@xen-orchestra/async-map' + +const array = await asyncMap(collection, iteratee) +``` diff --git a/@xen-orchestra/audit-core/README.md b/@xen-orchestra/audit-core/README.md new file mode 100644 index 000000000..a68720303 --- /dev/null +++ b/@xen-orchestra/audit-core/README.md @@ -0,0 +1,28 @@ + + +# @xen-orchestra/audit-core [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/audit-core)](https://npmjs.org/package/@xen-orchestra/audit-core) ![License](https://badgen.net/npm/license/@xen-orchestra/audit-core) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/audit-core)](https://packagephobia.now.sh/result?p=@xen-orchestra/audit-core) + +## Install + +Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/audit-core): + +``` +> npm install --save @xen-orchestra/audit-core +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/audit-core/USAGE.md b/@xen-orchestra/audit-core/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/babel-config/README.md b/@xen-orchestra/babel-config/README.md new file mode 100644 index 000000000..ba45ff888 --- /dev/null +++ b/@xen-orchestra/babel-config/README.md @@ -0,0 +1,18 @@ + + +# @xen-orchestra/babel-config [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/babel-config/USAGE.md b/@xen-orchestra/babel-config/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/backups-cli/README.md b/@xen-orchestra/backups-cli/README.md new file mode 100644 index 000000000..719d1b2cd --- /dev/null +++ b/@xen-orchestra/backups-cli/README.md @@ -0,0 +1,28 @@ + + +# @xen-orchestra/backups-cli [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/backups-cli)](https://npmjs.org/package/@xen-orchestra/backups-cli) ![License](https://badgen.net/npm/license/@xen-orchestra/backups-cli) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/backups-cli)](https://packagephobia.now.sh/result?p=@xen-orchestra/backups-cli) + +## Install + +Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/backups-cli): + +``` +> npm install --global @xen-orchestra/backups-cli +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/backups-cli/USAGE.md b/@xen-orchestra/backups-cli/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/backups/README.md b/@xen-orchestra/backups/README.md new file mode 100644 index 000000000..213219d5e --- /dev/null +++ b/@xen-orchestra/backups/README.md @@ -0,0 +1,28 @@ + + +# @xen-orchestra/backups [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/backups)](https://npmjs.org/package/@xen-orchestra/backups) ![License](https://badgen.net/npm/license/@xen-orchestra/backups) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/backups)](https://packagephobia.now.sh/result?p=@xen-orchestra/backups) + +## Install + +Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/backups): + +``` +> npm install --save @xen-orchestra/backups +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/backups/USAGE.md b/@xen-orchestra/backups/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/cr-seed-cli/README.md b/@xen-orchestra/cr-seed-cli/README.md new file mode 100644 index 000000000..b315164dd --- /dev/null +++ b/@xen-orchestra/cr-seed-cli/README.md @@ -0,0 +1,28 @@ + + +# @xen-orchestra/cr-seed-cli [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/cr-seed-cli)](https://npmjs.org/package/@xen-orchestra/cr-seed-cli) ![License](https://badgen.net/npm/license/@xen-orchestra/cr-seed-cli) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/cr-seed-cli)](https://packagephobia.now.sh/result?p=@xen-orchestra/cr-seed-cli) + +## Install + +Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/cr-seed-cli): + +``` +> npm install --global @xen-orchestra/cr-seed-cli +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/cr-seed-cli/USAGE.md b/@xen-orchestra/cr-seed-cli/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/cron/README.md b/@xen-orchestra/cron/README.md index 3ed6be5c9..3ca51cc7c 100644 --- a/@xen-orchestra/cron/README.md +++ b/@xen-orchestra/cron/README.md @@ -1,5 +1,9 @@ + + # @xen-orchestra/cron [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/cron)](https://npmjs.org/package/@xen-orchestra/cron) ![License](https://badgen.net/npm/license/@xen-orchestra/cron) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/cron)](https://packagephobia.now.sh/result?p=@xen-orchestra/cron) + > Focused, well maintained, cron parser/scheduler ## Install @@ -10,6 +14,8 @@ Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/cron) > npm install --save @xen-orchestra/cron ``` +## Usage + ### Pattern syntax ``` @@ -109,25 +115,6 @@ job.start() job.stop() ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -141,4 +128,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/cron/USAGE.md b/@xen-orchestra/cron/USAGE.md new file mode 100644 index 000000000..991c43712 --- /dev/null +++ b/@xen-orchestra/cron/USAGE.md @@ -0,0 +1,98 @@ +### Pattern syntax + +``` + +``` + +Each entry can be: + +- a single value +- a range (`0-23` or `*/2`) +- a list of values/ranges (`1,8-12`) + +A wildcard (`*`) can be used as a shortcut for the whole range +(`first-last`). + +Step values can be used in conjunctions with ranges. For instance, +`1-7/2` is the same as `1,3,5,7`. + +| Field | Allowed values | +| ---------------- | ------------------------------------------------------------------ | +| minute | 0-59 | +| hour | 0-23 | +| day of the month | 1-31 or 3-letter names (`jan`, `feb`, …) | +| month | 0-11 | +| day of week | 0-7 (0 and 7 both mean Sunday) or 3-letter names (`mon`, `tue`, …) | + +> Note: the month range is 0-11 to be compatible with +> [cron](https://github.com/kelektiv/node-cron), it does not appear to +> be very standard though. + +### API + +`createSchedule(pattern: string, zone: string = 'utc'): Schedule` + +> Create a new schedule. + +- `pattern`: the pattern to use, see [the syntax](#pattern-syntax) +- `zone`: the timezone to use, use `'local'` for the local timezone + +```js +import { createSchedule } from '@xen-orchestra/cron' + +const schedule = createSchedule('0 0 * * sun', 'America/New_York') +``` + +`Schedule#createJob(fn: Function): Job` + +> Create a new job from this schedule. + +- `fn`: function to execute, if it returns a promise, it will be + awaited before scheduling the next run. + +```js +const job = schedule.createJob(() => { + console.log(new Date()) +}) +``` + +`Schedule#next(n: number): Array` + +> Returns the next dates matching this schedule. + +- `n`: number of dates to return + +```js +schedule.next(2) +// [ 2018-02-11T05:00:00.000Z, 2018-02-18T05:00:00.000Z ] +``` + +`Schedule#startJob(fn: Function): () => void` + +> Start a new job from this schedule and return a function to stop it. + +- `fn`: function to execute, if it returns a promise, it will be + awaited before scheduling the next run. + +```js +const stopJob = schedule.startJob(() => { + console.log(new Date()) +}) +stopJob() +``` + +`Job#start(): void` + +> Start this job. + +```js +job.start() +``` + +`Job#stop(): void` + +> Stop this job. + +```js +job.stop() +``` diff --git a/@xen-orchestra/defined/README.md b/@xen-orchestra/defined/README.md index bd189f72d..d987349c8 100644 --- a/@xen-orchestra/defined/README.md +++ b/@xen-orchestra/defined/README.md @@ -1,6 +1,8 @@ -# @xen-orchestra/defined [![Build Status](https://travis-ci.org/${pkg.shortGitHubPath}.png?branch=master)](https://travis-ci.org/${pkg.shortGitHubPath}) + -> ${pkg.description} +# @xen-orchestra/defined [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/defined)](https://npmjs.org/package/@xen-orchestra/defined) ![License](https://badgen.net/npm/license/@xen-orchestra/defined) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/defined)](https://packagephobia.now.sh/result?p=@xen-orchestra/defined) ## Install @@ -10,29 +12,6 @@ Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/defin > npm install --save @xen-orchestra/defined ``` -## Usage - -**TODO** - -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -46,4 +25,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/defined/USAGE.md b/@xen-orchestra/defined/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/emit-async/README.md b/@xen-orchestra/emit-async/README.md index e5a7cd860..7e6d7567d 100644 --- a/@xen-orchestra/emit-async/README.md +++ b/@xen-orchestra/emit-async/README.md @@ -1,6 +1,8 @@ -# @xen-orchestra/emit-async [![Build Status](https://travis-ci.org/${pkg.shortGitHubPath}.png?branch=master)](https://travis-ci.org/${pkg.shortGitHubPath}) + -> ${pkg.description} +# @xen-orchestra/emit-async [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/emit-async)](https://npmjs.org/package/@xen-orchestra/emit-async) ![License](https://badgen.net/npm/license/@xen-orchestra/emit-async) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/emit-async)](https://packagephobia.now.sh/result?p=@xen-orchestra/emit-async) ## Install @@ -39,25 +41,6 @@ await ee.emitAsync( ) ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -71,4 +54,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/emit-async/USAGE.md b/@xen-orchestra/emit-async/USAGE.md new file mode 100644 index 000000000..a1877e7cb --- /dev/null +++ b/@xen-orchestra/emit-async/USAGE.md @@ -0,0 +1,26 @@ +```js +import EE from 'events' +import emitAsync from '@xen-orchestra/emit-async' + +const ee = new EE() +ee.emitAsync = emitAsync + +ee.on('start', async function() { + // whatever +}) + +// similar to EventEmmiter#emit() but returns a promise which resolves when all +// listeners have resolved +await ee.emitAsync('start') + +// by default, it will rejects as soon as one listener reject, you can customise +// error handling though: +await ee.emitAsync( + { + onError(error) { + console.warn(error) + }, + }, + 'start' +) +``` diff --git a/@xen-orchestra/fs/README.md b/@xen-orchestra/fs/README.md new file mode 100644 index 000000000..f3f551040 --- /dev/null +++ b/@xen-orchestra/fs/README.md @@ -0,0 +1,30 @@ + + +# @xen-orchestra/fs [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/fs)](https://npmjs.org/package/@xen-orchestra/fs) ![License](https://badgen.net/npm/license/@xen-orchestra/fs) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/fs)](https://packagephobia.now.sh/result?p=@xen-orchestra/fs) + +> The File System for Xen Orchestra backups. + +## Install + +Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/fs): + +``` +> npm install --global @xen-orchestra/fs +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/fs/USAGE.md b/@xen-orchestra/fs/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/log/README.md b/@xen-orchestra/log/README.md index 16a0b986d..b44500deb 100644 --- a/@xen-orchestra/log/README.md +++ b/@xen-orchestra/log/README.md @@ -1,6 +1,8 @@ + + # @xen-orchestra/log [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> \${pkg.description} +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/log)](https://npmjs.org/package/@xen-orchestra/log) ![License](https://badgen.net/npm/license/@xen-orchestra/log) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/log)](https://packagephobia.now.sh/result?p=@xen-orchestra/log) ## Install @@ -135,25 +137,6 @@ configure(transportSyslog()) configure(transportSyslog('tcp://syslog.company.lan')) ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -161,10 +144,10 @@ the code. You may: -- report any [issue](https://github.com/vatesfr/xen-orchestra/issues/) +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) you've encountered; - fork and create a pull request. ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/log/USAGE.md b/@xen-orchestra/log/USAGE.md new file mode 100644 index 000000000..a78724fdf --- /dev/null +++ b/@xen-orchestra/log/USAGE.md @@ -0,0 +1,122 @@ +Everywhere something should be logged: + +```js +import { createLogger } from '@xen-orchestra/log' + +const log = createLogger('my-module') + +log.debug('only useful for debugging') +log.info('this information is relevant to the user') +log.warn('something went wrong but did not prevent current action') +log.error('something went wrong') +log.fatal('service/app is going down') + +// you can add contextual info +log.debug('new API request', { + method: 'foo', + params: [ 'bar', 'baz' ] + user: 'qux' +}) + +// by convention, errors go into the `error` field +log.error('could not join server', { + error, + server: 'example.org', +}) +``` + +Then, at application level, configure the logs are handled: + +```js +import { createLogger } from '@xen-orchestra/log' +import { configure, catchGlobalErrors } from '@xen-orchestra/log/configure' +import transportConsole from '@xen-orchestra/log/transports/console' +import transportEmail from '@xen-orchestra/log/transports/email' + +const transport = transportEmail({ + service: 'gmail', + auth: { + user: 'jane.smith@gmail.com', + pass: 'H&NbECcpXF|pyXe#%ZEb', + }, + from: 'jane.smith@gmail.com', + to: ['jane.smith@gmail.com', 'sam.doe@yahoo.com'], +}) + +configure([ + { + // if filter is a string, then it is pattern + // (https://github.com/visionmedia/debug#wildcards) which is + // matched against the namespace of the logs + filter: process.env.DEBUG, + + transport: transportConsole(), + }, + { + // only levels >= warn + level: 'warn', + + transport, + }, +]) + +// send all global errors (uncaught exceptions, warnings, unhandled rejections) +// to this logger +catchGlobalErrors(createLogger('app')) +``` + +### Transports + +#### Console + +```js +import transportConsole from '@xen-orchestra/log/transports/console' + +configure(transportConsole()) +``` + +#### Email + +Optional dependency: + +``` +> yarn add nodemailer pretty-format +``` + +Configuration: + +```js +import transportEmail from '@xen-orchestra/log/transports/email' + +configure( + transportEmail({ + service: 'gmail', + auth: { + user: 'jane.smith@gmail.com', + pass: 'H&NbECcpXF|pyXe#%ZEb', + }, + from: 'jane.smith@gmail.com', + to: ['jane.smith@gmail.com', 'sam.doe@yahoo.com'], + }) +) +``` + +#### Syslog + +Optional dependency: + +``` +> yarn add split-host syslog-client +``` + +Configuration: + +```js +import transportSyslog from '@xen-orchestra/log/transports/syslog' + +// By default, log to udp://localhost:514 +configure(transportSyslog()) + +// But TCP, a different host, or a different port can be used +configure(transportSyslog('tcp://syslog.company.lan')) +``` diff --git a/@xen-orchestra/mixin/README.md b/@xen-orchestra/mixin/README.md index c76a4a3d9..5f1bc4381 100644 --- a/@xen-orchestra/mixin/README.md +++ b/@xen-orchestra/mixin/README.md @@ -1,6 +1,8 @@ -# @xen-orchestra/mixin [![Build Status](https://travis-ci.org/${pkg.shortGitHubPath}.png?branch=master)](https://travis-ci.org/${pkg.shortGitHubPath}) + -> ${pkg.description} +# @xen-orchestra/mixin [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/mixin)](https://npmjs.org/package/@xen-orchestra/mixin) ![License](https://badgen.net/npm/license/@xen-orchestra/mixin) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/mixin)](https://packagephobia.now.sh/result?p=@xen-orchestra/mixin) ## Install @@ -10,29 +12,6 @@ Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/mixin > npm install --save @xen-orchestra/mixin ``` -## Usage - -**TODO** - -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -46,4 +25,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/mixin/USAGE.md b/@xen-orchestra/mixin/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/@xen-orchestra/self-signed/README.md b/@xen-orchestra/self-signed/README.md index 90550a8b7..6b08a5a29 100644 --- a/@xen-orchestra/self-signed/README.md +++ b/@xen-orchestra/self-signed/README.md @@ -1,4 +1,8 @@ -# @xen-orchestra/self-signed + + +# @xen-orchestra/self-signed [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/self-signed)](https://npmjs.org/package/@xen-orchestra/self-signed) ![License](https://badgen.net/npm/license/@xen-orchestra/self-signed) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/self-signed)](https://packagephobia.now.sh/result?p=@xen-orchestra/self-signed) > Minimalist wrapper around openssl to generate a self signed certificate @@ -39,4 +43,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/self-signed/USAGE.md b/@xen-orchestra/self-signed/USAGE.md new file mode 100644 index 000000000..1a106c244 --- /dev/null +++ b/@xen-orchestra/self-signed/USAGE.md @@ -0,0 +1,13 @@ +```js +import { genSelfSigned } from '@xen-orchestra/self-signed' + +console.log(await genSelfSigned()) +// { +// cert: '-----BEGIN CERTIFICATE-----\n' + +// // content… +// '-----END CERTIFICATE-----\n', +// key: '-----BEGIN RSA PRIVATE KEY-----\n' + +// // content… +// '-----END RSA PRIVATE KEY-----\n' +// } +``` diff --git a/@xen-orchestra/template/README.md b/@xen-orchestra/template/README.md index fd10307c5..3e43275b1 100644 --- a/@xen-orchestra/template/README.md +++ b/@xen-orchestra/template/README.md @@ -1,5 +1,9 @@ + + # @xen-orchestra/template [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/@xen-orchestra/template)](https://npmjs.org/package/@xen-orchestra/template) ![License](https://badgen.net/npm/license/@xen-orchestra/template) [![PackagePhobia](https://badgen.net/packagephobia/install/@xen-orchestra/template)](https://packagephobia.now.sh/result?p=@xen-orchestra/template) + ## Install Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/template): @@ -30,25 +34,6 @@ const newString = myReplacer( newString === 'foo_COPY_{name}_42_32%' // true ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -62,4 +47,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/template/USAGE.md b/@xen-orchestra/template/USAGE.md new file mode 100644 index 000000000..d747a13fd --- /dev/null +++ b/@xen-orchestra/template/USAGE.md @@ -0,0 +1,19 @@ +Create a string replacer based on a pattern and a list of rules. + +```js +const myReplacer = compileTemplate('{name}_COPY_{name}_{id}_%%', { + '{name}': vm => vm.name_label, + '{id}': vm => vm.id, + '%': (_, i) => i, +}) + +const newString = myReplacer( + { + name_label: 'foo', + id: 42, + }, + 32 +) + +newString === 'foo_COPY_{name}_42_32%' // true +``` diff --git a/@xen-orchestra/upload-ova/README.md b/@xen-orchestra/upload-ova/README.md index e182b83fb..0b00e2c61 100644 --- a/@xen-orchestra/upload-ova/README.md +++ b/@xen-orchestra/upload-ova/README.md @@ -1,4 +1,6 @@ -# XO-UPLOAD-OVA + + +# @xen-orchestra/upload-ova [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > Basic CLI to upload ova files to Xen-Orchestra @@ -58,5 +60,4 @@ You may: ## License -XO-UPLOAD-OVA is released under the [AGPL -v3](http://www.gnu.org/licenses/agpl-3.0-standalone.html). +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/@xen-orchestra/upload-ova/USAGE.md b/@xen-orchestra/upload-ova/USAGE.md new file mode 100644 index 000000000..e539a473b --- /dev/null +++ b/@xen-orchestra/upload-ova/USAGE.md @@ -0,0 +1,40 @@ +``` +Usage: + + xo-upload-ova --register [--expiresIn duration] [] + Registers the XO instance to use. + + --expiresIn duration + Can be used to change the validity duration of the + authorization token (default: one month). + + xo-upload-ova --unregister + Remove stored credentials. + + xo-upload-ova --inspect + Displays the data that would be imported from the ova. + + xo-upload-ova --upload [--override = [=]+] + Actually imports the VM contained in to the Storage Repository . + Some parameters can be overridden from the file, consult --inspect to get the list. + Note: --override has to come last. By default arguments are string, prefix them with to type + them, ex. " --override nameLabel='new VM' memory=json:67108864 disks.vmdisk1.capacity=json:134217728" + +xo-upload-ova v0.1.0 + +``` + +#### Register your XO instance + +``` +> xo-upload-ova --register http://xo.my-company.net admin@admin.net admin +Successfully logged with admin@admin.net +``` + +Note: only a token will be saved in the configuration file. + +#### Import your .ova file + +``` +> xo-upload-ova --upload dsl.ova a7c630bf-b38c-489e-d3c3-e62507948980 --override 'nameLabel=dsl ' descriptionLabel='short desc' memory=json:671088640 disks.vmdisk1.descriptionLabel='disk description' disks.vmdisk1.capacity=json:1342177280 +``` diff --git a/packages/complex-matcher/README.md b/packages/complex-matcher/README.md index 2b12df17c..f2c73de24 100644 --- a/packages/complex-matcher/README.md +++ b/packages/complex-matcher/README.md @@ -1,6 +1,8 @@ + + # complex-matcher [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> ${pkg.description} +[![Package Version](https://badgen.net/npm/v/complex-matcher)](https://npmjs.org/package/complex-matcher) ![License](https://badgen.net/npm/license/complex-matcher) [![PackagePhobia](https://badgen.net/packagephobia/install/complex-matcher)](https://packagephobia.now.sh/result?p=complex-matcher) ## Install @@ -31,25 +33,6 @@ characters.filter(predicate) new CM.String('foo').createPredicate() ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -63,4 +46,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/packages/complex-matcher/USAGE.md b/packages/complex-matcher/USAGE.md new file mode 100644 index 000000000..ce1ad2353 --- /dev/null +++ b/packages/complex-matcher/USAGE.md @@ -0,0 +1,18 @@ +```js +import * as CM from 'complex-matcher' + +const characters = [ + { name: 'Catwoman', costumeColor: 'black' }, + { name: 'Superman', costumeColor: 'blue', hasCape: true }, + { name: 'Wonder Woman', costumeColor: 'blue' }, +] + +const predicate = CM.parse('costumeColor:blue hasCape?').createPredicate() + +characters.filter(predicate) +// [ +// { name: 'Superman', costumeColor: 'blue', hasCape: true }, +// ] + +new CM.String('foo').createPredicate() +``` diff --git a/packages/value-matcher/README.md b/packages/value-matcher/README.md index b89043989..d38d3b274 100644 --- a/packages/value-matcher/README.md +++ b/packages/value-matcher/README.md @@ -1,6 +1,8 @@ -# value-matcher [![Build Status](https://travis-ci.org/vatefr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatefr/xen-orchestra) + -> ${pkg.description} +# value-matcher [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/value-matcher)](https://npmjs.org/package/value-matcher) ![License](https://badgen.net/npm/license/value-matcher) [![PackagePhobia](https://badgen.net/packagephobia/install/value-matcher)](https://packagephobia.now.sh/result?p=value-matcher) ## Install @@ -30,25 +32,6 @@ import { createPredicate } from 'value-matcher' // ] ``` -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -62,4 +45,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/packages/value-matcher/USAGE.md b/packages/value-matcher/USAGE.md new file mode 100644 index 000000000..9f2a6a024 --- /dev/null +++ b/packages/value-matcher/USAGE.md @@ -0,0 +1,17 @@ +```js +import { createPredicate } from 'value-matcher' + +;[ + { user: 'sam', age: 65, active: false }, + { user: 'barney', age: 36, active: true }, + { user: 'fred', age: 40, active: false }, +].filter( + createPredicate({ + __or: [{ user: 'sam' }, { active: true }], + }) +) +// [ +// { user: 'sam', age: 65, active: false }, +// { user: 'barney', age: 36, active: true }, +// ] +``` diff --git a/packages/vhd-cli/README.md b/packages/vhd-cli/README.md index 7fb6c0ece..140b583f3 100644 --- a/packages/vhd-cli/README.md +++ b/packages/vhd-cli/README.md @@ -1,6 +1,8 @@ + + # vhd-cli [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> ${pkg.description} +[![Package Version](https://badgen.net/npm/v/vhd-cli)](https://npmjs.org/package/vhd-cli) ![License](https://badgen.net/npm/license/vhd-cli) [![PackagePhobia](https://badgen.net/packagephobia/install/vhd-cli)](https://packagephobia.now.sh/result?p=vhd-cli) ## Install @@ -10,31 +12,6 @@ Installation of the [npm package](https://npmjs.org/package/vhd-cli): > npm install --global vhd-cli ``` -## Usage - -``` -> vhd-cli -``` - -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -48,4 +25,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/packages/vhd-cli/USAGE.md b/packages/vhd-cli/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/packages/vhd-lib/README.md b/packages/vhd-lib/README.md new file mode 100644 index 000000000..7f92aa3f4 --- /dev/null +++ b/packages/vhd-lib/README.md @@ -0,0 +1,30 @@ + + +# vhd-lib [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/vhd-lib)](https://npmjs.org/package/vhd-lib) ![License](https://badgen.net/npm/license/vhd-lib) [![PackagePhobia](https://badgen.net/packagephobia/install/vhd-lib)](https://packagephobia.now.sh/result?p=vhd-lib) + +> Primitives for VHD file handling + +## Install + +Installation of the [npm package](https://npmjs.org/package/vhd-lib): + +``` +> npm install --save vhd-lib +``` + +## Contributions + +Contributions are _very_ welcomed, either on the documentation or on +the code. + +You may: + +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) + you've encountered; +- fork and create a pull request. + +## License + +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/vhd-lib/USAGE.md b/packages/vhd-lib/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/packages/xapi-explore-sr/README.md b/packages/xapi-explore-sr/README.md index e27f3d615..509d21153 100644 --- a/packages/xapi-explore-sr/README.md +++ b/packages/xapi-explore-sr/README.md @@ -1,5 +1,9 @@ + + # xapi-explore-sr [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xapi-explore-sr)](https://npmjs.org/package/xapi-explore-sr) ![License](https://badgen.net/npm/license/xapi-explore-sr) [![PackagePhobia](https://badgen.net/packagephobia/install/xapi-explore-sr)](https://packagephobia.now.sh/result?p=xapi-explore-sr) + > Display the list of VDIs (unmanaged and snapshots included) of a SR ## Install @@ -17,25 +21,6 @@ Installation of the [npm package](https://npmjs.org/package/xapi-explore-sr): Usage: xapi-explore-sr [--full] [] ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -49,4 +34,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/packages/xapi-explore-sr/USAGE.md b/packages/xapi-explore-sr/USAGE.md new file mode 100644 index 000000000..46b73bb94 --- /dev/null +++ b/packages/xapi-explore-sr/USAGE.md @@ -0,0 +1,4 @@ +``` +> xapi-explore-sr +Usage: xapi-explore-sr [--full] [] +``` diff --git a/packages/xen-api/README.md b/packages/xen-api/README.md index 32047bc24..1b43ede41 100644 --- a/packages/xen-api/README.md +++ b/packages/xen-api/README.md @@ -1,7 +1,21 @@ + + # xen-api [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xen-api)](https://npmjs.org/package/xen-api) ![License](https://badgen.net/npm/license/xen-api) [![PackagePhobia](https://badgen.net/packagephobia/install/xen-api)](https://packagephobia.now.sh/result?p=xen-api) + > Connector to the Xen API +## Install + +Installation of the [npm package](https://npmjs.org/package/xen-api): + +``` +> npm install --save xen-api +``` + +## Usage + Tested with: - XenServer 7.6 @@ -15,16 +29,6 @@ Tested with: - XenServer 6.2 - XenServer 5.6 -## Install - -Installation of the [npm package](https://npmjs.org/package/xen-api): - -``` -> npm install --save xen-api -``` - -## Usage - ### Library ```javascript @@ -108,25 +112,6 @@ root@xen1.company.net> findAll({ $type: 'VM' }).length 183 ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -134,10 +119,10 @@ the code. You may: -- report any [issue](https://github.com/xen-api/issues) +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) you've encountered; - fork and create a pull request. ## License -ISC © [Julien Fontanet](https://github.com/julien-f) +[ISC](hhttps://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr) diff --git a/packages/xen-api/USAGE.md b/packages/xen-api/USAGE.md new file mode 100644 index 000000000..19b446e9a --- /dev/null +++ b/packages/xen-api/USAGE.md @@ -0,0 +1,95 @@ +Tested with: + +- XenServer 7.6 +- XenServer 7.5 +- XenServer 7.4 +- XenServer 7.3 +- XenServer 7.2 +- XenServer 7.1 +- XenServer 7 +- XenServer 6.5 +- XenServer 6.2 +- XenServer 5.6 + +### Library + +```javascript +const { createClient } = require('xen-api') + +const xapi = createClient({ + url: 'https://xen1.company.net', + allowUnauthorized: false, + auth: { + user: 'root', + password: 'important secret password', + }, + readOnly: false, +}) +``` + +Options: + +- `url`: address of a host in the pool we are trying to connect to +- `allowUnauthorized`: whether to accept self-signed certificates +- `auth`: credentials used to sign in (can also be specified in the URL) +- `readOnly = false`: if true, no methods with side-effects can be called +- `callTimeout`: number of milliseconds after which a call is considered failed (can also be a map of timeouts by methods) + +```js +// Force connection. +xapi.connect().catch(error => { + console.error(error) +}) + +// Watch objects. +xapi.objects.on('add', objects => { + console.log('new objects:', objects) +}) +``` + +> Note: all objects are frozen and cannot be altered! + +Custom fields on objects (hidden − ie. non enumerable): + +- `$type`: the type of the object (`VM`, `task`, …); +- `$ref`: the (opaque) reference of the object; +- `$id`: the identifier of this object (its UUID if any, otherwise its reference); +- `$pool`: the pool object this object belongs to. + +Furthermore, any field containing a reference (or references if an +array) can be resolved by prepending the field name with a `$`: + +```javascript +console.log(xapi.pool.$master.$resident_VMs[0].name_label) +// vm1 +``` + +### CLI + +A CLI is provided to help exploration and discovery of the XAPI. + +``` +> xen-api xen1.company.net root +Password: ****** +root@xen1.company.net> xapi.status +'connected' +root@xen1.company.net> xapi.pool.master +'OpaqueRef:ec7c5147-8aee-990f-c70b-0de916a8e993' +root@xen1.company.net> xapi.pool.$master.name_label +'xen1' +``` + +You can optionally prefix the address by a protocol: `https://` (default) or `http://`. + +In case of error due to invalid or self-signed certificates you can use the `--allow-unauthorized` flag (or `--au`): + +``` +> xen-api --au xen1.company.net root +``` + +To ease searches, `find()` and `findAll()` functions are available: + +``` +root@xen1.company.net> findAll({ $type: 'VM' }).length +183 +``` diff --git a/packages/xo-acl-resolver/README.md b/packages/xo-acl-resolver/README.md index 2c0c7c59f..42b785812 100644 --- a/packages/xo-acl-resolver/README.md +++ b/packages/xo-acl-resolver/README.md @@ -1,6 +1,10 @@ + + # xo-acl-resolver [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> [Xen-Orchestra](http://xen-orchestra.com/) internal: do ACLs resolution. +[![Package Version](https://badgen.net/npm/v/xo-acl-resolver)](https://npmjs.org/package/xo-acl-resolver) ![License](https://badgen.net/npm/license/xo-acl-resolver) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-acl-resolver)](https://packagephobia.now.sh/result?p=xo-acl-resolver) + +> Xen-Orchestra internal: do ACLs resolution ## Install @@ -42,28 +46,6 @@ if ( } ``` -## Development - -### Installing dependencies - -``` -> npm install -``` - -### Compilation - -The sources files are watched and automatically recompiled on changes. - -``` -> npm run dev -``` - -### Tests - -``` -> npm run test-dev -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -77,4 +59,4 @@ You may: ## License -ISC © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-acl-resolver/USAGE.md b/packages/xo-acl-resolver/USAGE.md new file mode 100644 index 000000000..8ffcb07b0 --- /dev/null +++ b/packages/xo-acl-resolver/USAGE.md @@ -0,0 +1,29 @@ +```js +import check from 'xo-acl-resolver' + +// This object contains a list of permissions returned from +// xo-server's acl.getCurrentPermissions. +const permissions = { + /* ... */ +} + +// This function should returns synchronously an object from an id. +const getObject = id => { + /* ... */ +} + +// For a single object: +if (check(permissions, getObject, objectId, permission)) { + console.log(`${permission} set for object ${objectId}`) +} + +// For multiple objects/permissions: +if ( + check(permissions, getObject, [ + [object1Id, permission1], + [object12d, permission2], + ]) +) { + console.log('all permissions checked') +} +``` diff --git a/packages/xo-cli/README.md b/packages/xo-cli/README.md index 79b94d701..0a4ebcd44 100644 --- a/packages/xo-cli/README.md +++ b/packages/xo-cli/README.md @@ -1,17 +1,17 @@ -# XO-CLI + -[![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](http://travis-ci.org/vatesfr/xen-orchestra) -[![Dependency Status](https://david-dm.org/vatesfr/xo-cli/status.svg?theme=shields.io)](https://david-dm.org/vatesfr/xo-cli) -[![devDependency Status](https://david-dm.org/vatesfr/xo-cli/dev-status.svg?theme=shields.io)](https://david-dm.org/vatesfr/xo-cli#info=devDependencies) +# xo-cli [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/xo-cli)](https://npmjs.org/package/xo-cli) ![License](https://badgen.net/npm/license/xo-cli) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-cli)](https://packagephobia.now.sh/result?p=xo-cli) > Basic CLI for Xen-Orchestra ## Install -#### [npm](https://npmjs.org/package/xo-cli) +Installation of the [npm package](https://npmjs.org/package/xo-cli): ``` -npm install -g xo-cli +> npm install --global xo-cli ``` ## Usage @@ -129,25 +129,6 @@ encoding by prefixing with `json:`: A separate utility, [`xo-upload-ova`](https://github.com/vatesfr/xen-orchestra/blob/master/@xen-orchestra/upload-ova/README.md), can be used to import `.ova` files. -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production (automatically called by npm install) -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -161,5 +142,4 @@ You may: ## License -XO-CLI is released under the [AGPL -v3](http://www.gnu.org/licenses/agpl-3.0-standalone.html). +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-cli/USAGE.md b/packages/xo-cli/USAGE.md new file mode 100644 index 000000000..5925c6251 --- /dev/null +++ b/packages/xo-cli/USAGE.md @@ -0,0 +1,112 @@ +``` +> xo-cli --help +Usage: + + xo-cli --register [--expiresIn duration] [] + Registers the XO instance to use. + + --expiresIn duration + Can be used to change the validity duration of the + authorization token (default: one month). + + xo-cli --unregister + Remove stored credentials. + + xo-cli --list-commands [--json] []... + Returns the list of available commands on the current XO instance. + + The patterns can be used to filter on command names. + + xo-cli --list-objects [--]… [=]... + Returns a list of XO objects. + + -- + Restricts displayed properties to those listed. + + = + Restricted displayed objects to those matching the patterns. + + xo-cli [=]... + Executes a command on the current XO instance. +``` + +#### Register your XO instance + +``` +> xo-cli --register http://xo.my-company.net admin@admin.net admin +Successfully logged with admin@admin.net +``` + +Note: only a token will be saved in the configuration file. + +#### List available objects + +Prints all objects: + +``` +> xo-cli --list-objects +``` + +It is possible to filter on object properties, for instance to prints +all VM templates: + +``` +> xo-cli --list-objects type=VM-template +``` + +#### List available commands + +``` +> xo-cli --list-commands +``` + +Commands can be filtered using patterns: + +``` +> xo-cli --list-commands '{user,group}.*' +``` + +#### Execute a command + +The same syntax is used for all commands: `xo-cli =...` + +E.g., adding a new server: + +``` +> xo-cli server.add host=my.server.net username=root password=secret-password +42 +``` + +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 +encoding by prefixing with `json:`: + +``` +> xo-cli foo.bar baz='json:[1, 2, 3]' +``` + +##### Configuration export + +``` +> xo-cli xo.exportConfig @=config.json +``` + +##### VM export + +``` +> xo-cli vm.export vm=a01667e0-8e29-49fc-a550-17be4226783c @=vm.xva +``` + +##### XVA VM import + +``` +> xo-cli vm.import sr=60a6939e-8b0a-4352-9954-5bde44bcdf7d @=vm.xva +``` + +> Note: `xo-cli` only supports the import of XVA files. It will not import OVA files. + +##### OVA VM import + +A separate utility, [`xo-upload-ova`](https://github.com/vatesfr/xen-orchestra/blob/master/@xen-orchestra/upload-ova/README.md), can be used to import `.ova` files. diff --git a/packages/xo-collection/README.md b/packages/xo-collection/README.md index 49b2e366c..124dfcc8f 100644 --- a/packages/xo-collection/README.md +++ b/packages/xo-collection/README.md @@ -1,5 +1,9 @@ + + # xo-collection [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xo-collection)](https://npmjs.org/package/xo-collection) ![License](https://badgen.net/npm/license/xo-collection) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-collection)](https://packagephobia.now.sh/result?p=xo-collection) + > Generic in-memory collection with events ## Install @@ -230,25 +234,6 @@ const myView = new View(parentCollection, function predicate(value, key) { }) ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -262,4 +247,4 @@ You may: ## License -ISC © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-collection/USAGE.md b/packages/xo-collection/USAGE.md new file mode 100644 index 000000000..d1ed4796e --- /dev/null +++ b/packages/xo-collection/USAGE.md @@ -0,0 +1,217 @@ +```javascript +var Collection = require('xo-collection') +``` + +### Creation + +```javascript +// Creates a new collection. +var col = new Collection() +``` + +### Manipulation + +**Inserting a new item** + +```javascript +col.add('foo', true) +``` + +- **Throws** `DuplicateItem` if the item is already in the collection. + +**Updating an existing item** + +```javascript +col.update('foo', false) +``` + +- **Throws** `NoSuchItem` if the item is not in the collection. + +**Inserting or updating an item** + +```javascript +col.set('bar', true) +``` + +**Notifying an external update** + +> If an item is an object, it can be updated directly without using +> the `set`/`update` methods. +> +> To make sure the collection stays in sync and the correct events are +> sent, the `touch` method can be used to notify the change. + +```javascript +var baz = {} + +col.add('baz', baz) + +baz.prop = true +col.touch('baz') +``` + +> Because this is a much used pattern, `touch` returns the item to +> allow its direct modification. + +```javascript +col.touch('baz').prop = false +``` + +- **Throws** `NoSuchItem` if the item is not in the collection. +- **Throws** `IllegalTouch` if the item is not an object. + +**Removing an existing item** + +```javascript +col.remove('bar') +``` + +- **Throws** `NoSuchItem` if the item is not in the collection. + +**Removing an item without error** + +This is the symmetric method of `set()`: it removes the item if it +exists otherwise does nothing. + +```javascript +col.unset('bar') +``` + +**Removing all items** + +```javascript +col.clear() +``` + +### Query + +**Checking the existence of an item** + +```javascript +var hasBar = col.has('bar') +``` + +**Getting an existing item** + +```javascript +var foo = col.get('foo') + +// The second parameter can be used to specify a fallback in case the +// item does not exist. +var bar = col.get('bar', 6.28) +``` + +- **Throws** `NoSuchItem` if the item is not in the collection and no + fallback has been passed. + +**Getting a read-only view of the collection** + +> This property is useful for example to iterate over the collection +> or to make advanced queries with the help of utility libraries such +> as lodash. + +```javascript +var _ = require('lodash') + +// Prints all the items. +_.forEach(col.all, function(value, key) { + console.log('- %s: %j', key, value) +}) + +// Finds all the items which are objects and have a property +// `active` which equals `true`. +var results = _.where(col.all, { active: true }) +``` + +**Getting the number of items** + +```javascript +var size = col.size +``` + +### Events + +> The events are emitted asynchronously (at the next turn/tick of the +> event loop) and are deduplicated which means, for instance, that an +> addition followed by an update will result only in a single +> addition. + +**New items** + +```javascript +col.on('add', added => { + forEach(added, (value, key) => { + console.log('+ %s: %j', key, value) + }) +}) +``` + +**Updated items** + +```javascript +col.on('update', updated => { + forEach(updated, (value, key) => { + console.log('± %s: %j', key, value) + }) +}) +``` + +**Removed items** + +```javascript +col.on('remove', removed => { + // For consistency, `removed` is also a map but contrary to `added` + // and `updated`, the values associated to the keys are not + // significant since the items have already be removed. + + forEach(removed, (value, key) => { + console.log('- %s', key) + }) +}) +``` + +**End of update** + +> Emitted when all the update process is finished and all the update +> events has been emitted. + +```javascript +col.on('finish', () => { + console.log('the collection has been updated') +}) +``` + +### Iteration + +```javascript +for (const [key, value] of col) { + console.log('- %s: %j', key, value) +} + +for (const key of col.keys()) { + console.log('- %s', key) +} + +for (const value of col.values()) { + console.log('- %j', value) +} +``` + +### Views + +```javascript +const View = require('xo-collection/view') +``` + +> A view is a read-only collection which contains only the items of a +> parent collection which satisfy a predicate. +> +> It is updated at most once per turn of the event loop and therefore +> can be briefly invalid. + +```javascript +const myView = new View(parentCollection, function predicate(value, key) { + // This function should return a boolean indicating whether the + // current item should be in this view. +}) +``` diff --git a/packages/xo-common/README.md b/packages/xo-common/README.md index 2c76c2f8a..8cb5ffab7 100644 --- a/packages/xo-common/README.md +++ b/packages/xo-common/README.md @@ -1,5 +1,9 @@ + + # xo-common [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xo-common)](https://npmjs.org/package/xo-common) ![License](https://badgen.net/npm/license/xo-common) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-common)](https://packagephobia.now.sh/result?p=xo-common) + > Code shared between [XO](https://xen-orchestra.com) server and clients ## Install @@ -10,29 +14,6 @@ Installation of the [npm package](https://npmjs.org/package/xo-common): > npm install --save xo-common ``` -## Usage - -**TODO** - -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -46,4 +27,4 @@ You may: ## License -AGPL3 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-common/USAGE.md b/packages/xo-common/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/packages/xo-import-servers-csv/README.md b/packages/xo-import-servers-csv/README.md index 48084cc5f..7bc8156ae 100644 --- a/packages/xo-import-servers-csv/README.md +++ b/packages/xo-import-servers-csv/README.md @@ -1,5 +1,9 @@ + + # xo-import-servers-csv [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xo-import-servers-csv)](https://npmjs.org/package/xo-import-servers-csv) ![License](https://badgen.net/npm/license/xo-import-servers-csv) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-import-servers-csv)](https://packagephobia.now.sh/result?p=xo-import-servers-csv) + > CLI to import servers in XO from a CSV file ## Install @@ -29,25 +33,6 @@ Shell command: > xo-import-servers-csv 'https://xo.company.tld' admin@admin.net admin < servers.csv ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -61,4 +46,4 @@ You may: ## License -ISC © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-import-servers-csv/USAGE.md b/packages/xo-import-servers-csv/USAGE.md new file mode 100644 index 000000000..a386574d5 --- /dev/null +++ b/packages/xo-import-servers-csv/USAGE.md @@ -0,0 +1,16 @@ +`servers.csv`: + +```csv +host,username,password +xs1.company.net,user1,password1 +xs2.company.net:8080,user2,password2 +http://xs3.company.net,user3,password3 +``` + +> The CSV file can also contains these optional fields: `label`, `autoConnect`, `allowUnauthorized`. + +Shell command: + +``` +> xo-import-servers-csv 'https://xo.company.tld' admin@admin.net admin < servers.csv +``` diff --git a/packages/xo-lib/README.md b/packages/xo-lib/README.md index 92231867c..fb4a342cb 100644 --- a/packages/xo-lib/README.md +++ b/packages/xo-lib/README.md @@ -1,19 +1,17 @@ + + # xo-lib [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> Library to connect to XO-Server. +[![Package Version](https://badgen.net/npm/v/xo-lib)](https://npmjs.org/package/xo-lib) ![License](https://badgen.net/npm/license/xo-lib) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-lib)](https://packagephobia.now.sh/result?p=xo-lib) + +> Library to connect to XO-Server ## Install Installation of the [npm package](https://npmjs.org/package/xo-lib): ``` -npm install --save xo-lib -``` - -Then require the package: - -```javascript -import Xo from 'xo-lib' +> npm install --save xo-lib ``` ## Usage @@ -22,6 +20,8 @@ import Xo from 'xo-lib' > browser, the location of the current page will be used. ```javascript +import Xo from 'xo-lib' + // Connect to XO. const xo = new Xo({ url: 'https://xo.company.tld' }) @@ -133,25 +133,6 @@ xo.on('authenticationFailure', () => { }) ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -165,4 +146,4 @@ You may: ## License -ISC © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-lib/USAGE.md b/packages/xo-lib/USAGE.md new file mode 100644 index 000000000..c0aa3e601 --- /dev/null +++ b/packages/xo-lib/USAGE.md @@ -0,0 +1,116 @@ +> If the URL is not provided and the current environment is a web +> browser, the location of the current page will be used. + +```javascript +import Xo from 'xo-lib' + +// Connect to XO. +const xo = new Xo({ url: 'https://xo.company.tld' }) + +// Let's start by opening the connection. +await xo.open() + +// Must sign in before being able to call any methods (all calls will +// be buffered until signed in). +await xo.signIn({ + email: 'admin@admin.net', + password: 'admin', +}) + +console('signed as', xo.user) +``` + +The credentials can also be passed directly to the constructor: + +```javascript +const xo = Xo({ + url: 'https://xo.company.tld', + credentials: { + email: 'admin@admin.net', + password: 'admin', + }, +}) + +xo.open() + +xo.on('authenticated', () => { + console.log(xo.user) +}) +``` + +> If the URL is not provided and the current environment is a web +> browser, the location of the current page will be used. + +### Connection + +```javascript +await xo.open() + +console.log('connected') +``` + +### Disconnection + +```javascript +xo.close() + +console.log('disconnected') +``` + +### Method call + +```javascript +const token = await xo.call('token.create') + +console.log('Token created', token) +``` + +### Status + +The connection status is available through the status property which +is _open_, _connecting_ or _closed_. + +```javascript +console.log('%s to xo-server', xo.status) +``` + +### Current user + +Information about the user account used to sign in is available +through the `user` property. + +```javascript +console.log('Current user is', xo.user) +``` + +> This property is null when the status is not connected. + +### Events + +```javascript +xo.on('open', () => { + console.log('connected') +}) +``` + +```javascript +xo.on('closed', () => { + console.log('disconnected') +}) +``` + +```javascript +xo.on('notification', function(notif) { + console.log('notification:', notif.method, notif.params) +}) +``` + +```javascript +xo.on('authenticated', () => { + console.log('authenticated as', xo.user) +}) + +xo.on('authenticationFailure', () => { + console.log('failed to authenticate') +}) +``` diff --git a/packages/xo-remote-parser/README.md b/packages/xo-remote-parser/README.md index 1bb9a8f60..f23693a84 100644 --- a/packages/xo-remote-parser/README.md +++ b/packages/xo-remote-parser/README.md @@ -1,6 +1,8 @@ -# xo-remote-parser [![Build Status](https://travis-ci.org/${pkg.shortGitHubPath}.png?branch=master)](https://travis-ci.org/${pkg.shortGitHubPath}) + -> ${pkg.description} +# xo-remote-parser [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + +[![Package Version](https://badgen.net/npm/v/xo-remote-parser)](https://npmjs.org/package/xo-remote-parser) ![License](https://badgen.net/npm/license/xo-remote-parser) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-remote-parser)](https://packagephobia.now.sh/result?p=xo-remote-parser) ## Install @@ -10,29 +12,6 @@ Installation of the [npm package](https://npmjs.org/package/xo-remote-parser): > npm install --save xo-remote-parser ``` -## Usage - -**TODO** - -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -46,4 +25,4 @@ You may: ## License -AGPL-3.0 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-remote-parser/USAGE.md b/packages/xo-remote-parser/USAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/packages/xo-server-audit/README.md b/packages/xo-server-audit/README.md index 94a9ccb70..d96b4220b 100644 --- a/packages/xo-server-audit/README.md +++ b/packages/xo-server-audit/README.md @@ -1,39 +1,14 @@ -# xo-server-audit [![Build Status](https://api.travis-ci.org/vatesfr/xo-server-audit.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + -> **TODO** +# xo-server-audit [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -## Install - -Installation of the [npm package](https://npmjs.org/package/xo-server-audit): - -``` -> npm install --global xo-server-audit -``` +> Audit plugin for XO-Server ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> yarn - -# Run the tests -> yarn test - -# Continuously compile -> yarn dev - -# Continuously run the tests -> yarn dev-test - -# Build for production -> yarn build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -47,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-audit/USAGE.md b/packages/xo-server-audit/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-audit/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-auth-github/README.md b/packages/xo-server-auth-github/README.md index fbffa2388..aca8c5bc0 100644 --- a/packages/xo-server-auth-github/README.md +++ b/packages/xo-server-auth-github/README.md @@ -1,18 +1,16 @@ + + # xo-server-auth-github [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > GitHub authentication plugin for XO-Server +## Usage + This plugin allows GitHub users to authenticate to Xen-Orchestra. The first time a user signs in, XO will create a new XO user with the same identifier. -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - -## Usage - > This plugin is based on [passport-github](https://github.com/jaredhanson/passport-github), > see [its documentation](https://github.com/jaredhanson/passport-github#configure-strategy) > for more information about the configuration. @@ -22,28 +20,6 @@ the web interface, see [the plugin documentation](https://xen-orchestra.com/docs ![Registering XO instance in GitHub](github.png) -## Development - -### Installing dependencies - -``` -> npm install -``` - -### Compilation - -The sources files are watched and automatically recompiled on changes. - -``` -> npm run dev -``` - -### Tests - -``` -> npm run test-dev -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -57,4 +33,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-auth-github/USAGE.md b/packages/xo-server-auth-github/USAGE.md new file mode 100644 index 000000000..d31005c2e --- /dev/null +++ b/packages/xo-server-auth-github/USAGE.md @@ -0,0 +1,13 @@ +This plugin allows GitHub users to authenticate to Xen-Orchestra. + +The first time a user signs in, XO will create a new XO user with the +same identifier. + +> This plugin is based on [passport-github](https://github.com/jaredhanson/passport-github), +> see [its documentation](https://github.com/jaredhanson/passport-github#configure-strategy) +> for more information about the configuration. + +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). + +![Registering XO instance in GitHub](github.png) diff --git a/packages/xo-server-auth-google/README.md b/packages/xo-server-auth-google/README.md index 57537649f..8e5b625d6 100644 --- a/packages/xo-server-auth-google/README.md +++ b/packages/xo-server-auth-google/README.md @@ -1,18 +1,16 @@ + + # xo-server-auth-google [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > Google authentication plugin for XO-Server +## Usage + This plugin allows Google users to authenticate to Xen-Orchestra. The first time a user signs in, XO will create a new XO user with the same identifier. -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - -## Usage - > This plugin is based on [passport-google](https://google.com/jaredhanson/passport-google), > see [its documentation](https://google.com/jaredhanson/passport-google#configure-strategy) > for more information about the configuration. @@ -38,25 +36,6 @@ Add OAuth 2.0 credentials: Like all other xo-server plugins, it can be configured directly via the web iterface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -70,4 +49,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-auth-google/USAGE.md b/packages/xo-server-auth-google/USAGE.md new file mode 100644 index 000000000..50a998862 --- /dev/null +++ b/packages/xo-server-auth-google/USAGE.md @@ -0,0 +1,29 @@ +This plugin allows Google users to authenticate to Xen-Orchestra. + +The first time a user signs in, XO will create a new XO user with the +same identifier. + +> This plugin is based on [passport-google](https://google.com/jaredhanson/passport-google), +> see [its documentation](https://google.com/jaredhanson/passport-google#configure-strategy) +> for more information about the configuration. + +### Creating the Google project + +[Create a new project](https://console.developers.google.com/project): + +![](create-project.png) +![](create-project-2.png) + +Enable the Google+ API: + +![](enable-google+-api.png) + +Add OAuth 2.0 credentials: + +![](add-oauth2-credentials.png) +![](add-oauth2-credentials-2.png) + +### Add the plugin to XO-Server config + +Like all other xo-server plugins, it can be configured directly via +the web iterface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-auth-ldap/README.md b/packages/xo-server-auth-ldap/README.md index 759883cce..ce61f5afb 100644 --- a/packages/xo-server-auth-ldap/README.md +++ b/packages/xo-server-auth-ldap/README.md @@ -1,18 +1,16 @@ + + # xo-server-auth-ldap [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > LDAP authentication plugin for XO-Server +## Usage + This plugin allows LDAP users to authenticate to Xen-Orchestra. The first time a user signs in, XO will create a new XO user with the same identifier. -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - -## Usage - Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). @@ -43,25 +41,6 @@ could not authenticate john.smith 3. If found, a bind is attempted using the distinguished name of this user and the provided password. -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -75,4 +54,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-auth-ldap/USAGE.md b/packages/xo-server-auth-ldap/USAGE.md new file mode 100644 index 000000000..9bcf27b9d --- /dev/null +++ b/packages/xo-server-auth-ldap/USAGE.md @@ -0,0 +1,34 @@ +This plugin allows LDAP users to authenticate to Xen-Orchestra. + +The first time a user signs in, XO will create a new XO user with the +same identifier. + +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). + +If you have issues, you can use the provided CLI to gather more +information: + +``` +> xo-server-auth-ldap +? uri ldap://ldap.company.net +? fill optional certificateAuthorities? No +? fill optional checkCertificate? No +? fill optional bind? No +? base ou=people,dc=company,dc=net +? fill optional filter? No +configuration saved in ./ldap.cache.conf +? Username john.smith +? Password ***** +searching for entries... +0 entries found +could not authenticate john.smith +``` + +## Algorithm + +1. If `bind` is defined, attempt to bind using this user. +2. Searches for the user in the directory starting from the `base` + with the defined `filter`. +3. If found, a bind is attempted using the distinguished name of this + user and the provided password. diff --git a/packages/xo-server-auth-saml/README.md b/packages/xo-server-auth-saml/README.md index bfac50b5d..09e1193d3 100644 --- a/packages/xo-server-auth-saml/README.md +++ b/packages/xo-server-auth-saml/README.md @@ -1,18 +1,16 @@ + + # xo-server-auth-saml [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > SAML authentication plugin for XO-Server +## Usage + This plugin allows SAML users to authenticate to Xen-Orchestra. The first time a user signs in, XO will create a new XO user with the same identifier. -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - -## Usage - > This plugin is based on [passport-saml](https://github.com/bergie/passport-saml), > see [its documentation](https://github.com/bergie/passport-saml#configure-strategy) > for more information about the configuration. @@ -24,25 +22,6 @@ the web interface, see [the plugin documentation](https://xen-orchestra.com/docs > you must configure its callback URL to > `http://xo.company.net/signin/saml/callback`! -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -56,4 +35,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-auth-saml/USAGE.md b/packages/xo-server-auth-saml/USAGE.md new file mode 100644 index 000000000..b08f18fc1 --- /dev/null +++ b/packages/xo-server-auth-saml/USAGE.md @@ -0,0 +1,15 @@ +This plugin allows SAML users to authenticate to Xen-Orchestra. + +The first time a user signs in, XO will create a new XO user with the +same identifier. + +> This plugin is based on [passport-saml](https://github.com/bergie/passport-saml), +> see [its documentation](https://github.com/bergie/passport-saml#configure-strategy) +> for more information about the configuration. + +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). + +> Important: When registering your instance to your identity provider, +> you must configure its callback URL to +> `http://xo.company.net/signin/saml/callback`! diff --git a/packages/xo-server-backup-reports/README.md b/packages/xo-server-backup-reports/README.md index fb12406f6..592392eb9 100644 --- a/packages/xo-server-backup-reports/README.md +++ b/packages/xo-server-backup-reports/README.md @@ -1,37 +1,16 @@ -# xo-server-backup-reports [![Build Status](https://api.travis-ci.org/vatesfr/xo-server-backup-reports.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) + + +# xo-server-backup-reports [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > Backup reports plugin for XO-Server -XO-Server plugin which sends email reports and Xmpp messages when backup jobs are done. - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - ## Usage +XO-Server plugin which sends email reports and Xmpp messages when backup jobs are done. + Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -45,4 +24,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-backup-reports/USAGE.md b/packages/xo-server-backup-reports/USAGE.md new file mode 100644 index 000000000..0592d0ac1 --- /dev/null +++ b/packages/xo-server-backup-reports/USAGE.md @@ -0,0 +1,4 @@ +XO-Server plugin which sends email reports and Xmpp messages when backup jobs are done. + +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-load-balancer/README.md b/packages/xo-server-load-balancer/README.md index 76ec80f91..36cad0eb7 100644 --- a/packages/xo-server-load-balancer/README.md +++ b/packages/xo-server-load-balancer/README.md @@ -1,38 +1,14 @@ + + # xo-server-load-balancer [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -XO-Server plugin that allows load balancing. - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Load balancer for XO-Server ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -### Installing dependencies - -``` -> npm install -``` - -### Compilation - -The sources files are watched and automatically recompiled on changes. - -``` -> npm run dev -``` - -### Tests - -``` -> npm run test-dev -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -46,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-load-balancer/USAGE.md b/packages/xo-server-load-balancer/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-load-balancer/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-perf-alert/README.md b/packages/xo-server-perf-alert/README.md index c6e542c62..c10318d75 100644 --- a/packages/xo-server-perf-alert/README.md +++ b/packages/xo-server-perf-alert/README.md @@ -1,10 +1,8 @@ + + # xo-server-perf-alert [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> Alert plugin for Xen Orchestra - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Sends alerts based on performance criteria ## Usage @@ -24,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-perf-alert/USAGE.md b/packages/xo-server-perf-alert/USAGE.md new file mode 100644 index 000000000..8368fbaf6 --- /dev/null +++ b/packages/xo-server-perf-alert/USAGE.md @@ -0,0 +1,2 @@ +Like all xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-sdn-controller/README.md b/packages/xo-server-sdn-controller/README.md index 4fd9b06f6..109c8f453 100644 --- a/packages/xo-server-sdn-controller/README.md +++ b/packages/xo-server-sdn-controller/README.md @@ -1,13 +1,13 @@ + + # xo-server-sdn-controller [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +> Creates pool-wide and cross-pool private networks + +## Usage + XO Server plugin that allows the creation of pool-wide and cross-pool private networks. -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - -## Documentation - Please see the plugin's [official documentation](https://xen-orchestra.com/docs/sdn_controller.html). ## Contributions @@ -23,4 +23,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-sdn-controller/USAGE.md b/packages/xo-server-sdn-controller/USAGE.md new file mode 100644 index 000000000..28b13ae9a --- /dev/null +++ b/packages/xo-server-sdn-controller/USAGE.md @@ -0,0 +1,3 @@ +XO Server plugin that allows the creation of pool-wide and cross-pool private networks. + +Please see the plugin's [official documentation](https://xen-orchestra.com/docs/sdn_controller.html). diff --git a/packages/xo-server-test/README.md b/packages/xo-server-test/README.md index d18da0984..7faaa00f6 100644 --- a/packages/xo-server-test/README.md +++ b/packages/xo-server-test/README.md @@ -1,7 +1,11 @@ -# xo-server-test + + +# xo-server-test [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > Test client for Xo-Server +## Usage + Tests are ran sequentially to avoid concurrency issues. ## Adding a test @@ -145,10 +149,10 @@ describe('issue', () => { - You can run only tests related to changed files, and review the failed output by using: `> yarn test --watch` -- ⚠ Warning: snapshots ⚠ +- ⚠ Warning: snapshots ⚠ After each run of the tests, check that snapshots are not inadvertently modified. -- ⚠ Jest known issue ⚠ +- ⚠ Jest known issue ⚠ If a test timeout is triggered the next async tests can fail, it's due to an inadvertently modified snapshots. As a workaround, you can clean your git working tree and re-run jest using a large timeout: `> yarn test --testTimeout=100000` @@ -165,4 +169,4 @@ You may: ## License -ISC © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-test/USAGE.md b/packages/xo-server-test/USAGE.md new file mode 100644 index 000000000..69d94f9c0 --- /dev/null +++ b/packages/xo-server-test/USAGE.md @@ -0,0 +1,149 @@ +Tests are ran sequentially to avoid concurrency issues. + +## Adding a test + +### Organization + +``` +src +├─ user +| ├─ __snapshots__ +| | └─ index.spec.js.snap +| └─ index.spec.js +├─ job +| └─ index.spec.js +├─ issues +¦ └─ index.spec.js +¦ +├─ _xoConnection.js +└─ util.js +``` + +The tests can describe: + +- XO methods or scenarios: + +`src/user/index.js` + +```js +import xo from '../_xoConnection' + +describe('user', () => { + // testing a method + describe('.set()', () => { + it('sets an email', async () => { + // some tests using xo methods and helpers from _xoConnection.js + const id = await xo.createTempUser(SIMPLE_USER) + expect(await xo.call('user.set', params)).toBe(true) + expect(await xo.getUser(id)).toMatchSnapshot({ + id: expect.any(String), + }) + }) + }) + + // testing a scenario + test('create two users, modify a user email to be the same with the other and fail trying to connect them', () => { + /* some tests */ + }) +}) +``` + +- issues + +`src/issues/index.js` + +```js +describe('issue', () => { + test('5454', () => { + /* some tests */ + }) +}) +``` + +### Best practices + +- The test environment must remain the same before and after each test: + + - each resource created must be deleted + - existing resources should not be altered + +- Make a sentence for the title of the test. It must be clear and consistent. + +- If the feature you want to test is not implemented : write it and skip it, using `it.skip()`. + +- Take values ​​that cover the maximum of testing possibilities. + +- If you make tests which keep track of large object, it is better to use snapshots. + +- `_xoConnection.js` contains helpers to create temporary resources and to interface with XO. + You can use it if you need to create resources which will be automatically deleted after the test: + + ```javascript + import xo from '../_xoConnection' + + describe('.create()', () => { + it('creates a user without permission', async () => { + // The user will be deleted automatically at the end of the test + const userId = await xo.createTempUser({ + email: 'wayne1@vates.fr', + password: 'batman1', + }) + expect(await xo.getUser(userId)).toMatchSnapshot({ + id: expect.any(String), + }) + }) + }) + ``` + + The available helpers: + + - `createTempUser(params)` + - `getUser(id)` + - `createTempJob(params)` + - `createTempBackupNgJob(params)` + - `createTempVm(params)` + - `getSchedule(predicate)` + +## Usage + +- Before running the tests, you have to create a config file for xo-server-test. + + ``` + > cp sample.config.toml ~/.config/xo-server-test/config.toml + ``` + + And complete it. + +- To run the tests: + + ``` + > npm ci + > yarn test + ``` + + You get all the test suites passed (`PASS`) or failed (`FAIL`). + + ``` + > yarn test + yarn run v1.9.4 + $ jest + PASS src/user/user.spec.js + PASS src/job/job.spec.js + PASS src/backupNg/backupNg.spec.js + + Test Suites: 3 passed, 3 total + Tests: 2 skipped, 36 passed, 38 total + Snapshots: 35 passed, 35 total + Time: 7.257s, estimated 8s + Ran all test suites. + Done in 7.92s. + ``` + +- You can run only tests related to changed files, and review the failed output by using: `> yarn test --watch` + +- ⚠ Warning: snapshots ⚠ + After each run of the tests, check that snapshots are not inadvertently modified. + +- ⚠ Jest known issue ⚠ + If a test timeout is triggered the next async tests can fail, it's due to an inadvertently modified snapshots. + As a workaround, you can clean your git working tree and re-run jest using a large timeout: `> yarn test --testTimeout=100000` diff --git a/packages/xo-server-transport-email/README.md b/packages/xo-server-transport-email/README.md index ba849c32a..2312ef20b 100644 --- a/packages/xo-server-transport-email/README.md +++ b/packages/xo-server-transport-email/README.md @@ -1,35 +1,14 @@ + + # xo-server-transport-email [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > xo-server plugin to send emails -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -43,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-email/USAGE.md b/packages/xo-server-transport-email/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-transport-email/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-transport-icinga2/README.md b/packages/xo-server-transport-icinga2/README.md index fff817ac7..2eac6a151 100644 --- a/packages/xo-server-transport-icinga2/README.md +++ b/packages/xo-server-transport-icinga2/README.md @@ -1,18 +1,14 @@ + + # xo-server-transport-icinga2 [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> xo-server plugin to send status to icinga2 server - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Sends backup runs statuses to icinga2 server ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - ### `Xo#sendIcinga2Status({ status, message })` This xo method is called to send a passive check to icinga2 and change the status of a service. @@ -21,23 +17,6 @@ It has two parameters: - status: it's the service status in icinga2 (0: OK | 1: WARNING | 2: CRITICAL | 3: UNKNOWN). - message: it's the status information in icinga2. -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -51,4 +30,4 @@ You may: ## License -AGPL3 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-icinga2/USAGE.md b/packages/xo-server-transport-icinga2/USAGE.md new file mode 100644 index 000000000..c3573b188 --- /dev/null +++ b/packages/xo-server-transport-icinga2/USAGE.md @@ -0,0 +1,10 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). + +### `Xo#sendIcinga2Status({ status, message })` + +This xo method is called to send a passive check to icinga2 and change the status of a service. +It has two parameters: + +- status: it's the service status in icinga2 (0: OK | 1: WARNING | 2: CRITICAL | 3: UNKNOWN). +- message: it's the status information in icinga2. diff --git a/packages/xo-server-transport-nagios/README.md b/packages/xo-server-transport-nagios/README.md index ea94c226c..eb16b4b51 100644 --- a/packages/xo-server-transport-nagios/README.md +++ b/packages/xo-server-transport-nagios/README.md @@ -1,18 +1,14 @@ + + # xo-server-transport-nagios [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -> ${pkg.description} - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Send backup runs statuses to Nagios ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - ### `Xo#sendPassiveCheck( { status, message })` This xo method is called to send a passive check to nagios and change the status of a service. @@ -21,23 +17,6 @@ It has two parameters: - status: it's the service status in Nagios (0: OK | 1: WARNING | 2: CRITICAL). - message: it's the status information in Nagios. -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -51,4 +30,4 @@ You may: ## License -AGPL3 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-nagios/USAGE.md b/packages/xo-server-transport-nagios/USAGE.md new file mode 100644 index 000000000..8f730eaf7 --- /dev/null +++ b/packages/xo-server-transport-nagios/USAGE.md @@ -0,0 +1,10 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). + +### `Xo#sendPassiveCheck( { status, message })` + +This xo method is called to send a passive check to nagios and change the status of a service. +It has two parameters: + +- status: it's the service status in Nagios (0: OK | 1: WARNING | 2: CRITICAL). +- message: it's the status information in Nagios. diff --git a/packages/xo-server-transport-slack/README.md b/packages/xo-server-transport-slack/README.md index 5bae8a3cf..e037830d0 100644 --- a/packages/xo-server-transport-slack/README.md +++ b/packages/xo-server-transport-slack/README.md @@ -1,11 +1,9 @@ + + # xo-server-transport-slack [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) > xo-server plugin to send messages to Slack/Mattermost -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). - ## Usage Like all other xo-server plugins, it can be configured directly via @@ -50,29 +48,6 @@ the web iterface, see [the plugin documentation](https://xen-orchestra.com/docs/ ![Mattermost](image/DocImg9.png) -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - -### `Xo#sendSlackMessage({ message })` - -This xo method is called to send the message passed in parameter to Slack or Mattermost. - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -86,4 +61,4 @@ You may: ## License -AGPL3 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-slack/USAGE.md b/packages/xo-server-transport-slack/USAGE.md new file mode 100644 index 000000000..e5c38e50c --- /dev/null +++ b/packages/xo-server-transport-slack/USAGE.md @@ -0,0 +1,41 @@ +Like all other xo-server plugins, it can be configured directly via +the web iterface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). You can also test the configuration plugin if it works. + +### Slack + +#### Generate the Webhook + +1. Log in your Slack team account +2. Click on the **Main menu** at the top and choose **Apps & Integrations** + + ![Apps & Integrations](image/DocImg1.png) + +3. Search **Incoming WebHooks** + + ![Incoming WebHooks](image/DocImg2.png) + +4. Click on **Add Configuration** + + ![Add Configuration](image/DocImg3.png) + +5. Choose the default channel and click on **Add Incoming WebHooks integration** + + ![Add Incoming WebHooks integration](image/DocImg4.png) + +6. Modify the default settings and click on **Save Settings** + + ![Save Settings](image/DocImg5.png) + +### Testing the plugin + +#### Slack + +![Slack configuration](image/DocImg6.png) + +![Slack](image/DocImg7.png) + +#### Mattermost + +![Mattermost configuration](image/DocImg8.png) + +![Mattermost](image/DocImg9.png) diff --git a/packages/xo-server-transport-xmpp/README.md b/packages/xo-server-transport-xmpp/README.md index 5a0152d3b..4d1c82ac1 100644 --- a/packages/xo-server-transport-xmpp/README.md +++ b/packages/xo-server-transport-xmpp/README.md @@ -1,35 +1,14 @@ + + # xo-server-transport-xmpp [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -XO-Server plugin which sends XMPP messages. - -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Transport Xmpp plugin for XO-Server ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -43,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-transport-xmpp/USAGE.md b/packages/xo-server-transport-xmpp/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-transport-xmpp/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-usage-report/README.md b/packages/xo-server-usage-report/README.md index f46e9bed0..bb90a8ec7 100644 --- a/packages/xo-server-usage-report/README.md +++ b/packages/xo-server-usage-report/README.md @@ -1,35 +1,14 @@ -# xo-server-usage-report [![Build Status](https://travis-ci.org/vatesfr/xo-server-usage-report.png?branch=master)](https://travis-ci.org/vatesfr/xo-server-usage-report) + -> \${pkg.description} +# xo-server-usage-report [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) -## Install - -For installing XO and the plugins from the sources, please take a look at [the documentation](https://xen-orchestra.com/docs/from_the_sources.html). +> Report resources usage with their evolution ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -43,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](http://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-usage-report/USAGE.md b/packages/xo-server-usage-report/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-usage-report/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-server-web-hooks/README.md b/packages/xo-server-web-hooks/README.md index 23ef515bb..eab11145f 100644 --- a/packages/xo-server-web-hooks/README.md +++ b/packages/xo-server-web-hooks/README.md @@ -1,29 +1,14 @@ + + # xo-server-web-hooks [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +> Sends HTTP requests on XO-Server API calls + ## Usage Like all other xo-server plugins, it can be configured directly via the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -37,4 +22,4 @@ You may: ## License -AGPL3 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-server-web-hooks/USAGE.md b/packages/xo-server-web-hooks/USAGE.md new file mode 100644 index 000000000..7076801ca --- /dev/null +++ b/packages/xo-server-web-hooks/USAGE.md @@ -0,0 +1,2 @@ +Like all other xo-server plugins, it can be configured directly via +the web interface, see [the plugin documentation](https://xen-orchestra.com/docs/plugins.html). diff --git a/packages/xo-vmdk-to-vhd/README.md b/packages/xo-vmdk-to-vhd/README.md index 62b787ced..78ff7844f 100644 --- a/packages/xo-vmdk-to-vhd/README.md +++ b/packages/xo-vmdk-to-vhd/README.md @@ -1,5 +1,9 @@ + + # xo-vmdk-to-vhd [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +[![Package Version](https://badgen.net/npm/v/xo-vmdk-to-vhd)](https://npmjs.org/package/xo-vmdk-to-vhd) ![License](https://badgen.net/npm/license/xo-vmdk-to-vhd) [![PackagePhobia](https://badgen.net/packagephobia/install/xo-vmdk-to-vhd)](https://packagephobia.now.sh/result?p=xo-vmdk-to-vhd) + > JS lib streaming a vmdk file to a vhd ## Install @@ -36,25 +40,6 @@ vmdkToVhd(fs.createReadStream(vmdkFileName)).then(function(stream) { }) ``` -## Development - -``` -# Install dependencies -> npm install - -# Run the tests -> npm test - -# Continuously compile -> npm run dev - -# Continuously run the tests -> npm run dev-test - -# Build for production (automatically called by npm install) -> npm run build -``` - ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -62,10 +47,10 @@ the code. You may: -- report any [issue](https://github.com/vatesfr/xen-orchestra/issues/) +- report any [issue](https://github.com/vatesfr/xen-orchestra/issues) you've encountered; - fork and create a pull request. ## License -AGPLv3.0 © [Vates SAS](https://vates.fr) +[AGPL-3.0-or-later](hhttps://spdx.org/licenses/AGPL-3.0-or-later) © [Vates SAS](https://vates.fr) diff --git a/packages/xo-vmdk-to-vhd/USAGE.md b/packages/xo-vmdk-to-vhd/USAGE.md new file mode 100644 index 000000000..c8d2ed355 --- /dev/null +++ b/packages/xo-vmdk-to-vhd/USAGE.md @@ -0,0 +1,23 @@ +To convert a VMDK stream to a Fixed VHD stream without buffering the entire input or output: + +```js +import { vmdkToVhd } from 'xo-vmdk-to-vhd' +import { createReadStream, createWriteStream } from 'fs' +;(async () => { + const stream = await vmdkToVhd(fs.createReadStream(vmdkFileName)) + + stream.pipe(fs.createWriteStream(vhdFileName)) +})() +``` + +or: + +```js +var vmdkToVhd = require('xo-vmdk-to-vhd').vmdkToVhd +var createReadStream = require('fs').createReadStream +var createWriteStream = require('fs').createWriteStream + +vmdkToVhd(fs.createReadStream(vmdkFileName)).then(function(stream) { + stream.pipe(fs.createWriteStream(vhdFileName)) +}) +``` diff --git a/scripts/README.md.tpl b/scripts/README.md.tpl index 97af50de9..a83cf98c2 100644 --- a/scripts/README.md.tpl +++ b/scripts/README.md.tpl @@ -2,24 +2,30 @@ # {{pkg.name}} [![Build Status](https://travis-ci.org/vatesfr/xen-orchestra.png?branch=master)](https://travis-ci.org/vatesfr/xen-orchestra) +{{#unless pkg.private}} +[![Package Version](https://badgen.net/npm/v/{{pkg.name}})](https://npmjs.org/package/{{pkg.name}}) ![License](https://badgen.net/npm/license/{{pkg.name}}) [![PackagePhobia](https://badgen.net/packagephobia/install/{{pkg.name}})](https://packagephobia.now.sh/result?p={{pkg.name}}) + +{{/unless}} {{#if pkg.description}} > {{pkg.description}} -{{/if}} +{{/if}} {{#unless pkg.private}} ## Install Installation of the [npm package](https://npmjs.org/package/{{pkg.name}}): ``` -> npm install --save {{pkg.name}} +> npm install --{{#if pkg.preferGlobal}}global{{^}}save{{/if}} {{pkg.name}} ``` -{{/unless}} +{{/unless}} +{{#if usage}} ## Usage {{{usage}}} +{{/if}} ## Contributions Contributions are _very_ welcomed, either on the documentation or on @@ -33,4 +39,4 @@ You may: ## License -{{pkg.license}} © [{{pkg.author.name}}]({{pkg.author.url}}) +[{{pkg.license}}](hhttps://spdx.org/licenses/{{pkg.license}}) © [{{pkg.author.name}}]({{pkg.author.url}})