Cpanel setup

[CrownParkComputing]

Morning

I have been using Nginx for a while on my old hosting cpanel. I have just upgraded and I am trying to setup a new proxy host. When you select cpanel it asks for :

cpanel_url = https://cpanel.example.com:2083/
cpanel_username = user
cpanel_password = hunter2

which I have set correctly for my new cpanel access, I seem to remember I also need to generate an API key and put that somewhere . Please can you help ??

[pustekuchen91]

I'm also trying to use cPanel API Token for renewal of an certificate. It seems that auth. with an api token is not possibel atm?

https://docs.cpanel.net/knowledge-base/security/how-to-use-cpanel-api-tokens/

It seems that cpanel uses the token as username. But if you remove cpanel_password it aint work, because the property is required. If its set e.g. to the token too. then the authentication fails.

I think we need a possability just to add an token.

[pustekuchen91]

What did work is just use your account credentials. it doenst matter if you have TFA enabled. But using an API Token would be nicer.

[usury]

Cpanel API Token IS Possible

After some experimentation today (22 Sep 2024), it IS possible to specify your Cpanel API token
(and not use/store your Cpanel account password) when generating "DNS Challenge" certificates
through npm admin user interface.

I did this by directly editing my credentials file after a successful certificate generation.
I deleted the cpanel_password line and added cpanel_token, resulting in a credentials
file that looks like this...

cpanel_url = https://cpanel.example.com
cpanel_username = my_cpanel_username
cpanel_token = my_cpanel_api_key

This makes sense. Cpanel's Own Documentation describes passing username (meaning your username, not the word "username") in requests to their API. (You don't have to make any requests to Cpanel's API, but certbot does, so username is still required, even when using a Cpanel API key.)

Upon selecting "Renew Now" from the three-dots menu for that certificate from npm admin user interface, the certificate renews successfully. This can be confirmed with...

user@host: $> docker exec -it <npm-container-name> cat /tmp/letsencrypt-log/letsencrypt.log

Where is this credentials file

Credentials files can be found in ./letsencrypt/credentials/ when your compose.yaml includes...

volumes:
  ./letsencrypt:/etc/letsencrypt

A Little Background

npm calls a program called certbot and feeds it the credentials you specify when creating a certificate
for DNS Challenge to Cpanel.

npm relies on plugin definitions within the file certbot-dns-plugins.json.

nginx-proxy-manager/global/certbot-dns-plugins.json

Lines 74 to 81 in 63d06da

	"cpanel": {
	"name": "cPanel",
	"package_name": "certbot-dns-cpanel",
	"version": "~=0.2.2",
	"dependencies": "",
	"credentials": "cpanel_url = https://cpanel.example.com:2083\ncpanel_username = user\ncpanel_password = hunter2",
	"full_plugin_name": "cpanel"
	},

npm calls certbot using a plugin called certbot-dns-cpanel. This is one of the places...

nginx-proxy-manager/backend/internal/certificate.js

Lines 870 to 878 in 63d06da

	let mainCmd = certbotCommand + ' certonly ' +
	'--config "' + letsencryptConfig + '" ' +
	'--work-dir "/tmp/letsencrypt-lib" ' +
	'--logs-dir "/tmp/letsencrypt-log" ' +
	'--cert-name "npm-' + certificate.id + '" ' +
	'--agree-tos ' +
	'--email "' + certificate.meta.letsencrypt_email + '" ' +
	'--domains "' + certificate.domain_names.join(',') + '" ' +
	'--authenticator ' + dnsPlugin.full_plugin_name + ' ' +

certbot-dns-cpanel is baked into certbot itself and is not part of npm whatsoever.
In the plugin-developer's code, it's clear that the plugin supports token...
https://github.com/badjware/certbot-dns-cpanel/blob/a774ed907dd02cd1f2714c94a79bf54e6e41303f/certbot_dns_cpanel/dns_cpanel.py#L49-L53

Furthermore, if both token and password are specified, password is ignored by the plugin. I suspect either
certbot or the plugin itself must strip off the leading cpanel_* from settings in the credentials file.

I believe it may be possible to provide a nonsense password when initially specifying credentials
in the npm admin user interface....

cpanel_url = https://cpanel.example.com
cpanel_username = my_cpanel_username
cpanel_token = my_cpanel_api_key
cpanel_password = LiterllyCanBeAnything

By specifying cpanel_password, the form validator for npm admin UI probably won't
complain about the password being missing, because there is one. The form validator expects
cpanel_password to be there presumably because the plugin definition (link further above)
expects cpanel_password to be there.

The underlying plugin will happily ignore that pasword once the plugin receives the credentials
file, so long as cpanel_token is defined.

I haven't tested this, as mine works now and writing a post here is already plenty time consuming.
Still, I wanted to share for others to stumble upon some day.

[usury]

Update to my earlier Comment on Current Discussion Thread

Oops

It turns out I was wrong about the cpanel Certbot plugin as it exists inside Nginx Proxy Manager (npm).

It absolutely WILL NOT use cpanel_token as I described it previously. Editing my credentials file to eliminate cpanel_password must have caused npm to pull that value from its internal database from when I first entered it. The npm logs seem to indicate something like that.

Not Giving Up

However, it is still possible to use a CPanel API token for authentication. It requires:

• forcing npm to install the most recent version of the plugin certbot-dns-cpanel
• the plugin certbot-dns-cpanel does not come packaged with letsencrypt or certbot or npm
• npm installs it on demand when it is first used (and again every time the container relaunches)
  • also evidenced by the container log files at launch

# the leading dot is "source" - it's not "./opt/certbot/...", but rather "source /opt/certbot/..."
. /opt/certbot/bin/activate && pip install --no-cache-dir  certbot-dns-cpanel~=0.2.2  && deactivate

# we have to get it to do...
. /opt/certbot/bin/activate && pip install --no-cache-dir  certbot-dns-cpanel~=0.4.0  && deactivate

Newer Version of certbot-dns-cpanel

It's easier than you'd think to get npm to install a newer version of the plugin.

The plugin developer's GitHub indicates that version 0.4.0 is the most recent version.

However, npm has a file called certbot-dns-plugins.json that tells it what version to install. It specifies version 0.2.2.

nginx-proxy-manager/global/certbot-dns-plugins.json

Lines 74 to 81 in 63d06da

	"cpanel": {
	"name": "cPanel",
	"package_name": "certbot-dns-cpanel",
	"version": "~=0.2.2",
	"dependencies": "",
	"credentials": "cpanel_url = https://cpanel.example.com:2083\ncpanel_username = user\ncpanel_password = hunter2",
	"full_plugin_name": "cpanel"
	},

The same file also appears to define the fields expected by the plugin.

What to Do

• download that file (from GitHub)
• edit it locally
• mount it into your npm container

Edited Section:

	"cpanel": {
		"name": "cPanel",
		"package_name": "certbot-dns-cpanel",
		"version": "~=0.4.0",
		"dependencies": "",
		"credentials": "cpanel_url = https://cpanel.example.com:2083\ncpanel_username = your_username\ncpanel_password = your_password\ncpanel_token = your_api_token",
		"full_plugin_name": "cpanel"
	},

I changed only the version and credentials line.

The new version of the plugin ignores cpanel_password when cpanel_token is present.

Your compose.yaml needs to mount the new file into the container. Your volumes: section will likely have additional volumes than shown here.

• my edited certbot-dns-plugins.json file is in my local directory ./letsencrypt_plugins
• yours can be anywhere that makes sense to you
• I used the long form for the volumes: section here just for clarity
• The one-line form appears commented-out

    volumes:
      - type: bind
        source: ./letsencrypt_plugins/certbot-dns-plugins(edited).json
        target: /app/global/certbot-dns-plugins.json

#   volumes:
#       - ./letsencrypt_plugins/certbot-dns-plugins(edited).json:/app/global/certbot-dns-plugins.json

Now You Can

• launch your npm container
• create a new SSL certificate through the browser UI
• select DNS Challenge
• select Cpanel from the list
• enter credentials that look something like this

cpanel_url = https://cpanel.example.com:2083
cpanel_username = your_username
cpanel_password = LiterallyAnythingHere
cpanel_token = your_api_token

Then generate the certificate. npm installs the specified version of the plugin certbot-dns-cpanel and it works!

For whatever reason the template loaded into the entry form when selecting CPanel from the list does not reflect the edits made to file certbot-dns-plugins.json. I don't know where npm gets that from or if it's cached somehow.

Is This a Bug

I don't know. More like a stale feature that is improved with a newer version of that feature. It seems like npm maintainers could update the version and fields template in the file certbot-dns-plugins.json for the plugin certbot-dns-cpanel. I barely know how to use GitHub so I have no idea how to do it myself.