From 33b3ad3037afdb52aefa9f13a92c99936884cb01 Mon Sep 17 00:00:00 2001 From: ale-rt Date: Wed, 12 Feb 2025 11:17:03 +0100 Subject: [PATCH 1/2] Move the how to to the Admin guide section --- .../add-emergency-user.md} | 0 docs/admin-guide/index.md | 1 + docs/backend/users-groups.md | 13 ++++++++++++ docs/backend/users-groups/index.md | 20 ------------------- 4 files changed, 14 insertions(+), 20 deletions(-) rename docs/{backend/users-groups/emergency-user.md => admin-guide/add-emergency-user.md} (100%) create mode 100644 docs/backend/users-groups.md delete mode 100644 docs/backend/users-groups/index.md diff --git a/docs/backend/users-groups/emergency-user.md b/docs/admin-guide/add-emergency-user.md similarity index 100% rename from docs/backend/users-groups/emergency-user.md rename to docs/admin-guide/add-emergency-user.md 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/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 -``` From 9d3abb9b0ac3a6cedf228cf394bc52b99237e3c7 Mon Sep 17 00:00:00 2001 From: ale-rt Date: Wed, 12 Feb 2025 11:51:33 +0100 Subject: [PATCH 2/2] Add some more examples and clarifications --- docs/admin-guide/add-emergency-user.md | 103 +++++++++++++++++-------- 1 file changed, 71 insertions(+), 32 deletions(-) diff --git a/docs/admin-guide/add-emergency-user.md b/docs/admin-guide/add-emergency-user.md index ab6fe4bb8d..05c49cc2cd 100644 --- a/docs/admin-guide/add-emergency-user.md +++ b/docs/admin-guide/add-emergency-user.md @@ -1,64 +1,103 @@ --- 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" + "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)= -# Emergency user +# Zope Manager Users -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. +Zope manager users have full access to the whole Zope instance. -First of all, do the following steps not in a production environment! +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)= -## Create an emergency user +## Adding a New Zope Manager 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. +There are multiple ways to create a Zope manager user, depending on how you created and managed your Zope instance. ```{important} -You should always stop your Plone site before adding a new user. +If you are running a standalone instance, it must be stopped before adding the 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`. +### 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. -(user-groups-emergency-user-pip-installation-label)= +If the user already exists: -### pip based Plone instance +- No user will be created +- The password will not be changed -You can run the following shell commands to create an emergency user. +The command will return a message like this: -```shell -./venv/bin/instance stop -./venv/bin/addzopeuser -c instance/etc/zope.conf -./venv/bin/instance start +```bash +$ bin/instance adduser foo baz +Created user: None ``` -Now you can login with the created user. +### Using the `addzopeuser` command +For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment. -(user-groups-emergency-user-buildout-installation-label)= +The `addzopeuser` script might also be available in `buildout` based installations. -### Buildout based Plone instance +Run in the terminal: -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 +```bash +$ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password +User username created. ``` -Now you can login with the created user. +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. +```