klaboor
Cadet
- Joined
- Jan 23, 2023
- Messages
- 4
Greetings.
You discovered new 'shell' ACME DNS authenticator method asking yourself how to use it.
Short theory before we begin.
ACME authentication is one of the ACME protocol function required to PROVE that you are authorized for requested domain. In this case this is done by placing random TXT DNS record on your DNS server.
Since you are here I'm sure you heard about acmesh project. If not, please visit this link
We will use acmesh, part of it to be specific because acmesh already covers many providers, but it does the whole issuing certificate process. We don't want that. We want also install certificate into TrueNAS, not just issue it.
This video will help you set everything you need except ACME DNS authentication with shell script and we will do that part right now.
TrueNAS SCALE - Adding LetsEncrypt Certificates
You don't need to be root, but keep doing everything under same user!
If you already use acmesh and you want to switch over this method, stop all acmesh related cron jobs or whatever jobs you have currently in place and skip to step 5.
1. Create some dataset dedicated to this script somewhere on your pool
/mnt/tank/acmeScript
2. Go 'System Settings' -> 'Shell' or use PuTTY or similar to get into shell.
3. Navigate to your new folder (dataset)
4. Clone acmesh project localy with git
5. Create empty script file (select name your choice)
6. Now you need to paste code into file. Open file in editor
7. Copy code below and paste it in file(hit SHIFT + Insert in UI Shell ro paste code)
Note.
This script will load main acme.sh script and related DNS provider script so we can use custom functions for DNS TXT record creation/removal ONLY.
It also creates logfile called acmeShellAuth.log next to your script file so you can check what is going on.
8. Now you need to change few lines to reflect your environment and DNS provider
before
export ACME_FOLDER="/mnt/pool/acme.sh"
after
export ACME_FOLDER="/mnt/tank/acmeScript/acme.sh"
b. Select your DNS provider. Navigate here dnsapi or here dnsapi2 and find your provider.
Each provider has it's own issue command. You need that --dns parameter value.
For example PowerDNS have dns_pdns, WEDOS have dns_wedos and so on.
You need to change it here
before
export PROVIDER="dns_provider"
after
export PROVIDER="dns_wedos"
c. Apply your login credentials, token, api password, whatever is valid for your provider.
My is WEDOS so I will demonstrate accordingly
before
export username="example@gmail.com"
export password="somePass"
after
export WEDOS_Username="klaboor@gmail.com"
export WEDOS_Wapipass="start123"
9. Check again you modified things correctly and save your script file. Hit CTRL+x
Save modified buffer? Hit 'y' for Yes and confirm with ENTER.
10. Change script file permissions because it has password inside.
Only you will be able to read, write and execute it
11. In UI navigate to 'Credentials' -> 'Certificates'
Click 'Add' in ACME DNS-Authenticators section
Choose 'Name' you like
'Authenticator' select shell
'Authenticator script' will be /mnt/tank/acmeScript/acmeShellAuth.sh
'Running user' root or admin or whatever user you are using
'Timeout' and 'Propagation delay' are set to 60 (when fields are empty) by default but it was not enough time in my case so I set both to 600
Click 'Save'
12. From now you can continue with steps described in video.
13. Once you have your new certificate in place there is one last step I didn't knew it has be done.
In UI navigate 'System Settings' -> 'General'
Click 'Settings' in GUI section and change 'GUI SSL Certificate' from truenas_default to the one you already installed.
Check 'Web Interface HTTP -> HTTPS Redirect' option and click 'Save'
Confirm web service restart and you should be set.
And thats it. Hope this little howto is clear and helpful.
Of course there is room for improvements and feedback is highly appreciated.
Enjoy!
You discovered new 'shell' ACME DNS authenticator method asking yourself how to use it.
Short theory before we begin.
ACME authentication is one of the ACME protocol function required to PROVE that you are authorized for requested domain. In this case this is done by placing random TXT DNS record on your DNS server.
Since you are here I'm sure you heard about acmesh project. If not, please visit this link
We will use acmesh, part of it to be specific because acmesh already covers many providers, but it does the whole issuing certificate process. We don't want that. We want also install certificate into TrueNAS, not just issue it.
This video will help you set everything you need except ACME DNS authentication with shell script and we will do that part right now.
TrueNAS SCALE - Adding LetsEncrypt Certificates
You don't need to be root, but keep doing everything under same user!
If you already use acmesh and you want to switch over this method, stop all acmesh related cron jobs or whatever jobs you have currently in place and skip to step 5.
1. Create some dataset dedicated to this script somewhere on your pool
/mnt/tank/acmeScript
2. Go 'System Settings' -> 'Shell' or use PuTTY or similar to get into shell.
3. Navigate to your new folder (dataset)
cd /mnt/tank/acmeScript4. Clone acmesh project localy with git
git clone https://github.com/acmesh-official/acme.sh.git5. Create empty script file (select name your choice)
touch acmeShellAuth.sh6. Now you need to paste code into file. Open file in editor
nano acmeShellAuth.sh7. Copy code below and paste it in file(hit SHIFT + Insert in UI Shell ro paste code)
Note.
This script will load main acme.sh script and related DNS provider script so we can use custom functions for DNS TXT record creation/removal ONLY.
It also creates logfile called acmeShellAuth.log next to your script file so you can check what is going on.
Code:
#!/bin/bash
### VARIABLES
# Logfile
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
LOGFILE="${SCRIPT_DIR}/acmeShellAuth.log"
# Source acmesh scripts
export ACME_FOLDER="/mnt/pool/acme.sh" # Change this path to reflect yourf environment
export ACME_DNSAPI="${ACME_FOLDER}/dnsapi"
export PROVIDER="dns_provider" # Find provider script in 'dnsapi' folder
source "${ACME_FOLDER}/acme.sh" > /dev/null 2>&1
source "${ACME_DNSAPI}/${PROVIDER}.sh" > /dev/null 2>&1
# Dns API authentication. See details for your provider https://github.com/acmesh-official/acme.sh/wiki/dnsapi
export username="example@gmail.com"
export password="somePass"
### FUNCTIONS
_log_output() {
echo `date "+[%a %b %d %H:%M:%S %Z %Y]"`" $1" >> ${LOGFILE}
}
### MAIN
_log_output "INFO Script started."
# File/folder validation
if [ ! -d "${ACME_FOLDER}" ]; then
_log_output "ERROR Invalid acme folder: ${ACME_FOLDER}"
return 1
fi
if [ ! -f "${LOGFILE}" ]; then
touch "${LOGFILE}"
chmod 500 "${LOGFILE}"
fi
# Main
if [ "${1}" == "set" ]; then
${PROVIDER}_add "${3}" "${4}" >> ${LOGFILE} 2>/dev/null
elif [ "${1}" == "unset" ]; then
${PROVIDER}_rm "${3}" "${4}" >> ${LOGFILE} 2>/dev/null
fi
_log_output "INFO Script finished."8. Now you need to change few lines to reflect your environment and DNS provider
a. Modify acme.sh path
before
export ACME_FOLDER="/mnt/pool/acme.sh"
after
export ACME_FOLDER="/mnt/tank/acmeScript/acme.sh"
b. Select your DNS provider. Navigate here dnsapi or here dnsapi2 and find your provider.
Each provider has it's own issue command. You need that --dns parameter value.
For example PowerDNS have dns_pdns, WEDOS have dns_wedos and so on.
You need to change it here
before
export PROVIDER="dns_provider"
after
export PROVIDER="dns_wedos"
c. Apply your login credentials, token, api password, whatever is valid for your provider.
My is WEDOS so I will demonstrate accordingly
before
export username="example@gmail.com"
export password="somePass"
after
export WEDOS_Username="klaboor@gmail.com"
export WEDOS_Wapipass="start123"
9. Check again you modified things correctly and save your script file. Hit CTRL+x
Save modified buffer? Hit 'y' for Yes and confirm with ENTER.
10. Change script file permissions because it has password inside.
Only you will be able to read, write and execute it
chmod 700 acmeShellAuth.sh11. In UI navigate to 'Credentials' -> 'Certificates'
Click 'Add' in ACME DNS-Authenticators section
Choose 'Name' you like
'Authenticator' select shell
'Authenticator script' will be /mnt/tank/acmeScript/acmeShellAuth.sh
'Running user' root or admin or whatever user you are using
'Timeout' and 'Propagation delay' are set to 60 (when fields are empty) by default but it was not enough time in my case so I set both to 600
Click 'Save'
12. From now you can continue with steps described in video.
13. Once you have your new certificate in place there is one last step I didn't knew it has be done.
In UI navigate 'System Settings' -> 'General'
Click 'Settings' in GUI section and change 'GUI SSL Certificate' from truenas_default to the one you already installed.
Check 'Web Interface HTTP -> HTTPS Redirect' option and click 'Save'
Confirm web service restart and you should be set.
And thats it. Hope this little howto is clear and helpful.
Of course there is room for improvements and feedback is highly appreciated.
Enjoy!
