github-repos/acme.sh
1
0
Fork 0
mirror of https://github.com/acmesh-official/acme.sh.git synced 2025-03-24 18:40:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

update Deploy the certificate to Synology DSM with new temp admin method

Scruel Tao 2024-02-22 18:20:12 +08:00
parent 03e6b956ba
commit 74e50a95a2
1 changed files with 37 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
deployhooks.md

@ -595,37 +595,49 @@ acme.sh --deploy -d example.com --deploy-hook panos --insecure
## 20. Deploy the certificate to Synology DSM
As pointed out [inside the deploy script file](https://github.com/acmesh-official/acme.sh/blob/0da839cce35f4ab014a6d62133fac03c8f4c6979/deploy/synology_dsm.sh#L11-L21) itself, only 3 simple steps are required for renewal:
As pointed out [inside the deploy script file](https://github.com/acmesh-official/acme.sh/blob/cf3839ececc8d53bb55446958f7345bb1f8f8c4c/deploy/synology_dsm.sh#L11-L27) itself, only 3 simple steps are required for deploy:
1. Set the required environment variables which used for authentication while deploying:
- (Recommend) Use an automatically created temp admin user by executing `export SYNO_USE_TEMP_ADMIN=1`.
In this way, you won't need to provide any admin credentials, and it will be automatically deleted after the script is executed. It depends on DSM built-in utils, so you won't able to use this way in docker.
Notice#1: if the script unexpectedly stopped during runtime (e.g., press "Ctrl+C" while executing), the temp admin user may remain without deletion, you can safely delete it manually (or rerun the script).
- (Default) Use your existing admin user by provide its credential (username, password, OTP):
1. Execute `export SYNO_Username="adminUser"` where `adminUser` is any user with sufficient administrative rights, e. g. `admin`.
2. Execute `export SYNO_Password="adminPassword"` where `adminPassword` is the chosen user's password.
2. Set optional environment variables, if you won't need to change the defaults, then just skip this step, all optional exports are as the following (shown values are the defaults):
- `export SYNO_Certificate=""` - to replace a specific certificate via description
- `export SYNO_Scheme="http"`
- `export SYNO_Hostname="localhost"`
- `export SYNO_Port="5000"`
- `export SYNO_Create=1` - to allow creating the certificate if it doesn't exist
- `export SYNO_Device_Name="CertRenewal"` - required for omitting 2FA-OTP
- `export SYNO_Device_ID=""` - required for omitting 2FA-OTP (only pro users may set)
3. Execute the command `acme.sh --deploy --deploy-hook synology_dsm -d example.com` to deploy the certificate for `example.com` to your DSM.
1. Execute `export SYNO_Username="adminUser"` where `adminUser` is any user with sufficient administrative rights, e. g. `admin`.
2. Execute `export SYNO_Password="adminPassword"` where `adminPassword` is the chosen user's password.
3. Execute `acme.sh --deploy --deploy-hook synology_dsm -d example.com` to deploy the certificate for `example.com` to your DSM.
Optional exports that can be set as well (shown values are the defaults):
* `export SYNO_Certificate=""` to replace a specific certificate via its description
* `export SYNO_Scheme="http"`
* `export SYNO_Hostname="localhost"`
* `export SYNO_Port="5000"`
* `export SYNO_Device_Name="CertRenewal"` - required for skipping 2FA-OTP, set via script upon first run
* `export SYNO_Device_ID=""` - required for skipping 2FA-OTP, set via script upon first run
### About the authentication
Additionally, when issuing a Let's Encrypt certificate instead of renewing it, `export SYNO_Create=1` must be executed _once_, too.
> If you installed `acme.sh` in DSM rather than docker, and executed `export SYNO_USE_TEMP_ADMIN=1`, feel free to skip this section, because we won't need your own credential at all. BTW, if your DSM lost the required built-in tools to create temp admin user, the script will let you know, so you can back here to learn more.
> We highly recommand you to choose the temp user new way if avaiable, so you won't need to provide any of your own DSM credential, and the script won't need to store relaetd credential (in plaintext) on your disk.
For accessing the DSM successfully, the script will require you to provide your admin user credential (username & password), you can do it by exporting them, and for the future automatic execution, the script will save them in your disk (in plaintext).
In recent DSM versions, Synology requires 2-factor authentication enabled for admin users, and requires the user to input TOTP (Time-based One Time Password) code for each API-based access, so the deprecated (still available for backward compatibility) setup requires `SYNO_TOTP_SECRET`, it will be provided to `oathtool` to get the code. However, this method has many flaws:
- requires the user to manually install `oathtool` in DSM, since it's not included in the DSM built-in toolkit.
- require the user to provide their TOTP **SECRET**, it will be provided to the third party CLI tool every time we execute the script, and will be saved (in plaintext) on user's disk.
The **new** setup method won't require generating TOTP each time - TOTP can be omitted by utilizing so-called parameter "device ID".
In the early version of the deployment script, the users need to get it like a pro - its a cookie value leisurely stored in their browser, usually via devtools, then execute `export SYNO_DEVICE_ID="<device_id>"`.
After a few updates, we simplified the process, so we can now act as the same as we are on web UI while deploying - script will ask you to input the TOTP code for the admin user (defined by `SYNO_Username`) only once, and then obtain to store the "device ID" info (still in plaintext) to your local configuration file, which can be used upon subsequent deployments.
The default device name is `CertRenewal`, you can select another name as your own wish by exporting it as `SYNO_Device_Name`.
### Additional optional parameters
When issuing a certificate (e.g., Let's Encrypt) for the first time instead of renewing it, `export SYNO_Create=1` must be executed _once_.
Any subsequent run won't need that variable, hence it's not saved within your configuration file at all.
By default, Synology requires 2-factor authentication via TOTP (Time-based One Time Password) for each user upon API-based access to any recent DSM version - which basically breaks any automated deployment, if you (rightfully!) refuse to provide the TOTP secret in plaintext to some 3rd party CLI-based tool, generating the TOTP code for you.
It's recommended to set `SYNO_Scheme` to `https`, `SYNO_Port` to `5001` and `SYNO_Hostname` to your actual DSM's domain (e.g., `nas.example.com`) instead of the defaults. Which increased security by TLS-based connection.
However, using `https` & `localhost` requires addition of the [`--insecure` command line argument](https://github.com/acmesh-official/acme.sh/wiki/Options-and-Params) to successfully deploy the certificate to DSM. Though, enabling HTTP/2 still might give you a `curl 16 error` warning, although the script succeeded anyways.
While legacy setups of `ACME.sh` continue to work with such a risky workaround (until Synology ultimately pulls the plug on that), new as well as security-sensitive users are expected to only use the secured API access method - which requires 1 additional step (executed only _once_) upon running the actual deploy command (see step 3 above):
* manual input of the TOTP code for the user defined via `SYNO_Username`
* optionally entering a "device name", if you don't like the default `CertRenewal` one
After that one-time manual input of the TOTP code, the deploy script request a so called `device ID` from the DSM API for the specified user.
That ID is saved to your local configuration file & used upon subsequent deployments, in turn eliminating the need for another TOTP code or, even worse, the TOTP secret as the previous script did.
Additionally, it's recommended to set `SYNO_Scheme` to `https`, `SYNO_Port` to `5001` & `SYNO_Hostname` to your actual DSM's FQDN, e. g. `nas.example.com` instead of `http` & `localhost`. That's because of increased security due to TLS-based connection instead of a plaintext one.
However, using `https` & `localhost` requires addition of the [`--insecure` command line argument](https://github.com/acmesh-official/acme.sh/wiki/Options-and-Params) to successfully deploy the certificate to DSM. Though, enabling HTTP/2 still might give you a `curl 16 error`, although the script succeeded anyways.
Afterwards, the certificate should show up inside `Control Panel` -> `Security` -> `Certificates` & can be assigned to specific services or set as the default certificate.
`SYNO_Certificate` is set as empty string by default, so the script will replace "default synology certificate" by your domain certificate, it should be all fine. however if you don't want to do so, you can always change it's value to anything you want to describe the certificate.
The deployed certificate should show up inside `Control Panel` -> `Security` -> `Certificates`, it can be assigned to specific services (or set as the default certificate).
## 21. Deploy the cert to OpenStack Barbican