diff --git a/docs/admin-guide/add-emergency-user.md b/docs/admin-guide/add-emergency-user.md new file mode 100644 index 0000000000..05c49cc2cd --- /dev/null +++ b/docs/admin-guide/add-emergency-user.md @@ -0,0 +1,103 @@ +--- +myst: + html_meta: + "description": "How to create an emergency user in an existing Zope instance" + "property=og:description": "How to create an emergency user in an existing Zope instance" + "property=og:title": "How to create an emergency user" + "keywords": "Plone, Zope, users, emergency user, administration, pip, buildout" +--- + +(user-groups-emergency-user-label)= + +# Zope Manager Users + +Zope manager users have full access to the whole Zope instance. + +Some installation methods automatically create a zope admin user for you already. + +The credentials for this user are usually: + +- username: `admin` +- password: `admin` + +There are multiple reasons why you might need to add a new Zope manager user, such as: + +- Your installation method did not create one. +- You lost access to your instance. +- You inherited a project without proper documentation. + +If you need to regain access to your instance, this user is also refered to as an emergency user. + +This guide explains how to add a Zope manager user to an existing Zope instance. + +```{note} +The emergency user is a superuser with full access to the Zope instance. +It is not limited to a specific Plone site. +Please be aware of the security implications. +``` + +(user-groups-create-an-emergency-user-label)= + +## Adding a New Zope Manager User + +There are multiple ways to create a Zope manager user, depending on how you created and managed your Zope instance. + +```{important} +If you are running a standalone instance, it must be stopped before adding the user. +``` + +### Using the `adduser` instance command + +If your site was installed with `buildout`, you can add a Zope manager user via an instance script. + +Run the following command in the terminal: + +```bash +$ bin/instance adduser username password +Created user: username +``` + +The name of the instance script might vary based on your installation. +Replace `username` and `password` with the desired values. + +If the user already exists: + +- No user will be created +- The password will not be changed + +The command will return a message like this: + +```bash +$ bin/instance adduser foo baz +Created user: None +``` + +### Using the `addzopeuser` command + +For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment. + +The `addzopeuser` script might also be available in `buildout` based installations. + +Run in the terminal: + +```bash +$ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password +User username created. +``` + +The `addzopeuser` script and `zope.conf` locations might vary based on your installations. +Replace `username` and `password` with the desired values. + +If the user already exists: + +- No user will be created +- The password will not be changed + +The command will return a message like this: + +```bash +$ .venv/bin/addzopeuser -c tmp/zeoclient/etc/zope.conf foo baz +Got no result back. User creation may have failed. +Maybe the user already exists and nothing is done then. +Or the implementation does not give info when it succeeds. +``` diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md index a4df3676fd..fdfd90ea34 100644 --- a/docs/admin-guide/index.md +++ b/docs/admin-guide/index.md @@ -30,6 +30,7 @@ install-pip run-plone add-site +add-emergency-user configure-zope add-ons export-import diff --git a/docs/backend/users-groups.md b/docs/backend/users-groups.md new file mode 100644 index 0000000000..9954103d1b --- /dev/null +++ b/docs/backend/users-groups.md @@ -0,0 +1,13 @@ +--- +myst: + html_meta: + "description": "" + "property=og:description": "" + "property=og:title": "" + "keywords": "" +--- + +(backend-users-groups-label)= + +# Users and Groups + diff --git a/docs/backend/users-groups/emergency-user.md b/docs/backend/users-groups/emergency-user.md deleted file mode 100644 index ab6fe4bb8d..0000000000 --- a/docs/backend/users-groups/emergency-user.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -myst: - html_meta: - "description": "Create an emergency user" - "property=og:description": "Create an emergency user" - "property=og:title": "Create an emergency user" - "keywords": "Plone, users, groups, emergency user, pip, buildout" ---- - -(user-groups-emergency-user-label)= - -# Emergency user - -An emergency user is one that you can use to regain administrative access to a Plone site. -If you lose the administrator password, or you inherit a project without proper documentation, you can create an emergency user. - -First of all, do the following steps not in a production environment! - - -(user-groups-create-an-emergency-user-label)= - -## Create an emergency user - -There are two procedures to create an emergency user, depending on how you created and manage the Plone site. -For both scenarios, the commands you run will stop the Plone site, add a new user, and start the Plone site. - -```{important} -You should always stop your Plone site before adding a new user. -``` - -```{important} -The new username must not be an existing one. -Therefore you should avoid the username `admin`, but use another arbitrary name, such as `admin2`. -``` - - -(user-groups-emergency-user-pip-installation-label)= - -### pip based Plone instance - -You can run the following shell commands to create an emergency user. - -```shell -./venv/bin/instance stop -./venv/bin/addzopeuser -c instance/etc/zope.conf -./venv/bin/instance start -``` - -Now you can login with the created user. - - -(user-groups-emergency-user-buildout-installation-label)= - -### Buildout based Plone instance - -With buildout and `plone.recipe.zope2instance`, you can run the following shell commands to create an emergency user. - -```shell -bin/instance stop -bin/instance adduser -bin/instance start -``` - -Now you can login with the created user. diff --git a/docs/backend/users-groups/index.md b/docs/backend/users-groups/index.md deleted file mode 100644 index 177cb7e38e..0000000000 --- a/docs/backend/users-groups/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -myst: - html_meta: - "description": "Managing users and groups in Plone" - "property=og:description": "Managing users and groups in Plone" - "property=og:title": "Managing users and groups in Plone" - "keywords": "user, groups, Plone" ---- - -(backend-users-groups-label)= - -# Users and groups - - -```{toctree} -:caption: Users and groups -:maxdepth: 2 - -emergency-user -```