The nuxeoctl script is located in the bin folder of your Nuxeo installation. It enables various options and commands (explained in details below). For MS Windows users, its equivalent is the nuxeoctl.bat script.
nuxeoctl Usage
Here is the Shell/Batch script usage:
nuxeoctl <command> [options] [--] [command parameters]
Issue nuxeoctl help to print this information.
- You can use multiple options at once but only one command.
- The values separated by
|are choices (|means "exclusive or"). - Option and command parameters between square brackets (
[]) are optional. - Options and commands can have some parameters, optional or not. An equal sign (
=) can be used (ie.-d org.nuxeo com.companyequals to-d=org.nuxeo,com.company). - Some options also have a shortcut (ie.
-hequals to--help). - Two dots (
..) means the command accepts repeated parameters. - Commands may need to be prefixed with
--to separate them from options when confusion arises.
See the Environment variables page for setting Nuxeo Home and Configuration paths.
Per-command Usage
nuxeoctl encrypt [--encrypt <algorithm>] [<clearValue>..] [-d [<categories>]|-q]
Output encrypted value for <clearValue>.
If <clearValue> is not provided, it is read from stdin.
nuxeoctl decrypt '<cryptedValue>'.. [-d [<categories>]|-q]
Output decrypted value for <cryptedValue>. The secret key is read from stdin.
nuxeoctl config [<key> <value>].. <key> [<value>] [--encrypt [<algorithm>]] [--set [<template>]] [-d [<categories>]|-q]
Set template or global parameters.
If <value> is not provided and the --set 'option' is used, then the value is read from stdin.
nuxeoctl config [--get] <key>.. [-d [<categories>]|-q]
Get value for the given key(s).
nuxeoctl config [--get-regexp] <regexp>.. [-d [<categories>]|-q]
Get value for the keys matching the given regular expression(s).
nuxeoctl help|status|showconf [-d [<categories>]|-q]
nuxeoctl configure [-d [<categories>]|-q|-hdw]
nuxeoctl wizard [-d [<categories>]|-q|--clid <arg>|--gui <true|false|yes|no>]
nuxeoctl stop [-d [<categories>]|-q|--gui <true|false|yes|no>]
nuxeoctl start|restart|console|startbg|restartbg [-d [<categories>]|-q|--clid <arg>|--gui <true|false|yes|no>|--strict|-hdw]
nuxeoctl mp-show [command parameters] [-d [<categories>]|-q|--clid <arg>|--xml|--json]
nuxeoctl mp-list|mp-listall|mp-init|mp-update [command parameters] [-d [<categories>]|-q|--clid <arg>|--xml|--json]
nuxeoctl mp-reset|mp-purge|mp-hotfix|mp-upgrade [command parameters] [-d [<categories>]|-q|--clid <arg>|--xml|--json|--accept <true|false|yes|no|ask>]
nuxeoctl mp-add|mp-install|mp-uninstall|mp-remove|mp-set|mp-request [command parameters] [-d [<categories>]|-q|--clid <arg>|--xml|--json|--nodeps|--relax <true|false|yes|no|ask>|--accept <true|false|yes|no|ask>|-s|-im]
nuxeoctl register [<username> [<project> [<type> <description>] [<pwd>]]]
Register an instance with Nuxeo Online Services.
nuxeoctl register --clid <arg>
Register an instance according to the given CLID file.
nuxeoctl register --renew [--clid <arg>]
Renew an instance registration with Nuxeo Online Services.
nuxeoctl pack <target> [-d [<categories>]|-q]
nuxeoctl connect-report [--output <file>|--gzip <*true|false|yes|no>|--pretty-print <true|*false|yes|no>]
Options
| Option | Description |
|---|---|
-h,--help |
Show detailed help. |
-q,--quiet |
Suppress information messages. |
-d,--debug <categories> |
Activate debug messages. (Since Nuxeo 7.4) <categories>: comma-separated Java categories to debug (default: org.nuxeo.launcher). |
-dc <categories> |
(Since Nuxeo 5.6) Deprecated: see <categories> on --debug option. |
--debug-launcher |
(Since Nuxeo 5.9.4) Linux-only. Activate Java debugging mode on the Launcher. |
--clid <arg> |
(Since Nuxeo 6.0) Use the provided instance CLID file. |
--xml |
(Since Nuxeo 5.6) Output XML for mp-* commands. |
--json |
(Since Nuxeo 5.6) Output JSON for mp-* commands. |
--gui <true|false|yes|no> |
(Since Nuxeo 5.6) Start the Graphical User Interface (aka Nuxeo Control Panel). Default is true on Windows and false on other platforms. |
--nodeps |
(Since Nuxeo 5.6) Ignore package dependencies and constraints. |
--relax <true|false|yes|no|ask> |
(Since Nuxeo 5.6) Allow relax constraint on current platform (default: ask). |
--accept <true|false|yes|no|ask> |
(Since Nuxeo 5.6) Accept, refuse or ask confirmation for all changes (default: ask).In non interactive mode, --accept=true also sets --relax=true if needed. |
-s,--snapshot |
(Since Nuxeo 5.9.1) Allow use of SNAPSHOT Marketplace packages. This option is implicit: on SNAPSHOT distributions (daily builds), if the command explicitly requests a SNAPSHOT package. |
-f,--force |
(Since Nuxeo 5.9.1) Deprecated: use --strict option instead. |
--strict |
(Since Nuxeo 7.4) Abort in error the start command when a component cannot be activated or if a server is already running. |
-im,--ignore-missing |
(Since Nuxeo 6.0) Ignore unknown packages on mp-add, mp-install and mp-set commands. |
-hdw,--hide-deprecation-warnings |
(Since Nuxeo 5.6) Hide deprecation warnings. |
--encrypt <algorithm> |
(Since Nuxeo 7.4) Activate encryption on the config command.This option can be used on the encrypt command to customize the encryption algorithm.<algorithm> is a cipher transformation of the form: "algorithm/mode/padding" or "algorithm".Default value is "AES/ECB/PKCS5Padding" (Advanced Encryption Standard, Electronic Cookbook Mode, PKCS5-style padding). |
--gzip |
Compress the output. |
--pretty-print |
Pretty print the output. |
--output <file> |
Write output in specified file. |
--set <template> |
(Since Nuxeo 7.4) Set the value for a given key. The value is stored in nuxeo.conf by default unless a template name is provided; if so, it is then stored in the template's nuxeo.defaults file.If the value is empty (''), then the property is unset. This option is implicit if no --get or --get-regexp option is used and there are exactly two parameters (key value). |
--get-regexp |
(Since Nuxeo 7.4) Get the value for all keys matching the given regular expression(s). |
--get |
(Since Nuxeo 7.4) Get the value for a given key. Returns error code 6 if the key was not found. This option is implicit if --set option is not used and there are more or less than two parameters. |
Commands
| Command | Description |
|---|---|
help |
Print this message. |
gui |
Deprecated: use start --gui true option instead. |
start |
Start Nuxeo server in background, waiting for effective start. Useful for batch executions requiring the server being immediately available after the script returned. Note: On Windows, the start command launches the Control Panel. |
stop |
Stop any Nuxeo server started with the same nuxeo.conf file. |
restart |
Restart Nuxeo server. |
config |
Get and set template or global parameters. |
encrypt |
Output encrypted value for a given parameter. |
decrypt |
Output decrypted value for a given parameter. |
configure |
Configure Nuxeo server with parameters from nuxeo.conf. |
wizard |
Start the wizard. |
console |
Start Nuxeo server in a console mode. Ctrl+C will stop it. |
status |
Print server running status. |
startbg |
Start Nuxeo server in background, without waiting for effective start. Useful for starting Nuxeo as a service. |
restartbg |
Restart Nuxeo server with a call to startbg after stop. |
pack |
Build a static archive. |
showconf |
Display the server configuration. |
connect-report |
Dump a json report about the running server. |
register |
Register the server with an existing Nuxeo Online Service account. |
mp-list |
List local Marketplace packages (including hotfixes). |
mp-listall |
List all Marketplace packages. |
mp-init |
Pre-cache Marketplace packages locally available in the distribution. |
mp-update |
Update cache of Marketplace packages list. |
mp-add |
Add Marketplace package(s) to local cache. You must provide the package file(s), name(s) or ID(s) as parameter. |
mp-install |
Run Marketplace package installation. It is automatically called at startup if installAfterRestart.log file exists in data directory. Else you must provide the package file(s), name(s) or ID(s) as parameter. |
mp-uninstall |
Uninstall Marketplace package(s). You must provide the package name(s) or ID(s) as parameter (see mp-list command).If uninstalling a package by its ID and other versions of the same package are available, the most up-to-date will be installed instead. |
mp-remove |
Remove Marketplace package(s). You must provide the package name(s) or ID(s) as parameter (see mp-list command). |
mp-reset |
Reset all packages to DOWNLOADED state. May be useful after a manual server upgrade. |
mp-set |
(Since Nuxeo 5.9.2) Install a list of Marketplace packages and remove those not in the list. |
mp-request |
Install and uninstall Marketplace package(s) in one command. You must provide a quoted list of package names or IDs prefixed with + (install) or - (uninstall). |
mp-purge |
Uninstall and remove all packages from the local cache. |
mp-hotfix |
Install all the available hotfixes for the current platform, but do not upgrade already installed hotfixes versions. For the latter, please use mp-upgrade (to upgrade everything) or mp-install with the desired version (to install a specific package) instead. (requires a registered instance).
|
mp-upgrade |
Get all the available upgrades for the Nuxeo Packages currently installed (including installed hotfixes and Studio package(s)). If a snapshot package is installed, it will not be reinstalled even if it has been updated. In this case, you should use mp-remove then mp-install instead. |
mp-show |
(Since Nuxeo 5.7.1) Show Marketplace package(s) information. You must provide the package file(s), name(s) or ID(s) as parameter. |
register |
Register your instance with an existing Connect account. You must provide the credentials, the project name or ID, its type and a description. |
The following commands are always executed in console/headless mode (no GUI): configure, mp-init, mp-purge, mp-add, mp-install, mp-uninstall, mp-request, mp-remove, mp-hotfix, mp-upgrade, mp-reset, mp-list, mp-listall, mp-update, status, showconf, mp-show, mp-set, config, encrypt, decrypt, help.
The following commands cannot be executed on a running server: pack, mp-init, mp-purge, mp-add, mp-install, mp-uninstall, mp-request, mp-remove, mp-hotfix, mp-upgrade, mp-reset.
Most mp-* commands will have different behavior if the instance is registered or not (they need an authenticated access to the private Marketplace channels).
If the server has no access to Internet, mp-* commands will only use packages available in the local cache.
If using a Nuxeo Package not compliant with the current platform, you will have to relax the constraint on current platform (see --relax option). Be very careful since that can lead to install other packages not designed for your current Nuxeo version unless you perform a unitary install (see --nodeps option).
Additional Parameters
All parameters following a command which accepts no parameter are passed to the Java process when executing the command. That can be used for specific installs on which you rely on server specific parameters.
Environment Variables
Here are the OS environment variables which are read by nuxeoctl.
| Variable | Description |
|---|---|
NUXEO_HOME |
Path to server root directory. |
NUXEO_CONF |
Path to nuxeo.conf file. |
PATH |
|
JAVA |
Path to the java executable. |
JAVA_HOME |
Path to the Java home directory. Can also be defined in nuxeo.conf. |
JAVA_OPTS |
Optional values passed to the JVM. Can also be defined in nuxeo.conf. |
REQUIRED_JAVA_VERSION |
Nuxeo requirement on Java version. |
Java Usage
Launcher can be run as a Java command, without using the Shell (nuxeoctl) or Batch (nuxeoctl.bat) script.
The equivalent Java command to Shell command is printed at startup. See the line starting with "Launcher command:". It can be reused for writing your own scripts.
Here is the Java usage:
java [-Dlauncher.java.opts="JVM options"] [-Dnuxeo.home="/path/to/nuxeo"] [-Dnuxeo.conf="/path/to/nuxeo.conf"] \
[-Djvmcheck=nofail] -jar "path/to/nuxeo-launcher.jar" \
[options] <command> [command parameters]
Java Options
| Option | Description |
|---|---|
launcher.java.opts |
Parameters for the server JVM (default are -Xms512m -Xmx1024m -XX:MaxPermSize=512m). |
nuxeo.home |
Nuxeo server root path (default is parent of called script). |
nuxeo.conf |
Path to nuxeo.conf file (default is $NUXEO_HOME/bin/nuxeo.conf). |
jvmcheck |
If equals to "nofail", will continue execution even if JVM does not fit requirements, else will exit. |
Commands
Additional Parameters
See the nuxeoctl additional parameters.
Exit Code Values
Exit code values are following the Linux Standard Base Core Specification 4.1.
If the status command was requested, nuxeoctl will return the following exit status codes:
| 0 | Program is running or service is OK |
| 3 | Program is not running |
| 4 | Program or service status is unknown |
In case of an error while processing any action except for status, nuxeoctl shall print an error message and exit with a non-zero status code:
| 1 | Generic or unspecified error |
| 2 | Invalid or excess argument(s) |
| 3 | Unimplemented feature |
| 4 | User had insufficient privilege |
| 5 | Program is not installed |
| 6 | Program is not configured |
| 7 | Program is not running |
Related Documentation