Acmefyer documentation

Overview

Acmefyer gets TLS certificates for your servers, renews them in good time and installs them where they are needed: in IIS, in Exchange, on the FortiGate, in nginx or Apache. The certificates come from certificate authorities such as Let's Encrypt that offer the ACME protocol.

This matters more and more: public certificates will soon be valid for only a few weeks, from March 2029 for at most 47 days. Renewing them by hand hardly works any more. Acmefyer does it automatically.

Acmefyer consists of two programs:

• acmefyer-server runs on one of your servers. It talks to the certificate authority, keeps track of all certificates and renews them. You use it in the browser.
• acmefyer-agent runs on the systems that are to receive a certificate. It fetches new certificates from the server itself and installs them locally. No port needs to be opened on the target systems, and the server needs no credentials for them.

Both programs are single program files for Windows and Linux that need nothing else.

Requirements

• A server with Windows or Linux (64-bit) for acmefyer-server. A VM of its own is plenty.
• Network connections of the server:
  • to the certificate authority, for example Let's Encrypt (HTTPS, port 443)
  • depending on the validation method: reachable from outside on port 80 (HTTP-01) or access to your DNS provider's interface (DNS-01), see Creating certificates
  • to www.wedigo.net (HTTPS, port 443) for updates and the license
  • if the server reaches the internet only through a proxy: see Internet access through a proxy
• Agents only need a connection to the Acmefyer server (port 8443 by default). They do not need internet access.
• A certificate for the Acmefyer server itself as soon as you use agents. Agents only connect over HTTPS, see HTTPS for the server.

Installation

Put the program file in a folder of its own, for example C:\Program Files\Acmefyer or /opt/acmefyer. Start Acmefyer by hand the first time, in a console window in that folder:

cd "C:\Program Files\Acmefyer"
.\acmefyer-server.exe

cd /opt/acmefyer
./acmefyer-server

On the first start, Acmefyer creates the file config.yaml with your settings in the folder, plus the database acmefyer.db and the folder data.

Run as a service

To keep Acmefyer running, also after the server restarts, set it up as a service. This needs administrator rights (on Linux sudo). Run the commands in the program folder, so the service uses the config.yaml there.

.\acmefyer-server.exe service install
.\acmefyer-server.exe service start

sudo ./acmefyer-server service install
sudo ./acmefyer-server service start

Should the service ever crash, Windows restarts it on its own.

You can also do this in the console window: tab Service (key 5), then i to set it up and s to start it. The console window must be opened with administrator rights for this, too.

Setup

First login

On the first start, Acmefyer creates the user admin with a random initial password. The password is shown only once: in the console window on the Dashboard tab and in the log. At the first login you choose your own password.

Open the interface on the server in the browser at http://127.0.0.1:8443, or press o in the console window.

On the first start Acmefyer also creates a master key and stores it in config.yaml (server.master_key). It encrypts every secret in the database: certificate keys, credentials for DNS providers, passwords for SSH and FortiGate. Without this key the database is worthless. Keep it with your backups.

Access from other computers

At first, the interface can only be reached on the server itself. That way nobody gets in from outside by accident. To open it from your workstation:

• press l in the console window, or
• set server.http_addr to 0.0.0.0:8443.

Then restart the service and open port 8443 in the server's firewall. You can change the port on the Settings tab of the console window (key 6) or in server.http_addr.

HTTPS for the server

As long as no certificate file is configured, the interface is unencrypted (HTTP). For your browser on your own network that may do for a while. Agents, however, are only accepted over HTTPS, so their credentials do not cross the network in the clear.

The easiest way is to let Acmefyer get the certificate for itself:

1. Create a certificate for the server's name, for example acme.example.com.
2. Add the target File (PEM) to it, run on the server, with a folder such as C:\Program Files\Acmefyer\tls.
3. Enter both files in the settings and restart the service:

server:
  http_addr: "0.0.0.0:8443"
  tls_cert: "tls/fullchain.pem"
  tls_key: "tls/privkey.pem"

When the certificate is renewed later, Acmefyer picks up the new files by itself, without a restart. Alternatively, put a web server with HTTPS in front, for example IIS or nginx.

Internet access through a proxy

In many company networks the server cannot reach the internet directly, only through a proxy. Then the license check, updates, the certificate authority, the interface of your DNS provider and notifications (Teams, Telegram, webhooks) need that proxy.

On Windows, Acmefyer takes over the proxy of the server by itself: the system-wide proxy (netsh winhttp show proxy) and otherwise the proxy from the Internet Options, together with its exceptions. Automatic configuration (PAC file, automatic detection) is not taken over. The log and the Settings tab of the console window show which proxy is used and where it comes from. Only if no proxy is set there, or Acmefyer should use a different one, enter it in Acmefyer:

1. In the console window, open the tab Settings (key 6).
2. Choose Proxy URL with the arrow keys, press Enter, type the address, for example http://10.10.75.1:8080, and press Enter again. If the proxy needs a login: http://user:password@10.10.75.1:8080. Acmefyer stores the password encrypted in the database, not in config.yaml.
3. Under Exceptions, enter the names that are reached directly, separated by commas, for example corp.example.com, webhook01.
4. Press t to test the connection to www.wedigo.net with the values entered. If it fails, Acmefyer says why and what helps.
5. Press s to save, then restart the service (on the same tab with R, if the service is running).

Or write it into config.yaml and restart the service. A password written there by hand is moved into the database at the next start:

proxy:
  url: "http://10.10.75.1:8080"
  no_proxy: ["corp.example.com", "webhook01"]

This server itself and all private addresses (10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x) are always reached directly. Add internal targets that you give by name, such as the address of a webhook on your own network, to the exceptions. Otherwise Acmefyer sends those requests to the proxy as well. A domain such as corp.example.com includes all names below it. E-mail (SMTP), SSH and LDAP never go through the proxy.

Names without a domain that Windows reaches directly (<local> in the exceptions) are not taken over: enter them in the exceptions, or use the full name.

Which proxy applies: first the setting in Acmefyer (proxy.url), then the environment variables HTTPS_PROXY and NO_PROXY, then the system-wide Windows proxy, then the Internet Options. Agents do not use a proxy: they only connect to the Acmefyer server, and also ignore HTTPS_PROXY.

Creating certificates

You create new certificates in the interface under Certificates with New. A wizard asks step by step:

1. Certificate authority. The default is Let's Encrypt Staging. This is a test environment: you can try everything safely there, but browsers and devices do not trust these certificates. For real certificates choose Let's Encrypt Production or another authority. ZeroSSL and Google Trust also need the credentials of your account there (EAB ID and key).
2. Names. The main name, such as www.example.com, and further names in the same certificate if you like. A wildcard certificate (*.example.com) only works with DNS-01.
3. Validation method. This is how you show the certificate authority that the name is yours.
4. Key and e-mail. The e-mail address receives notices from the certificate authority.

You can tell a test certificate by the Staging label in the list. Once everything works, create the same certificate again with a real certificate authority and delete the test certificate.

Validation methods

• HTTP-01 with the built-in web server: The certificate authority fetches an address on port 80. Acmefyer opens the port only while the validation runs. The name must point from the internet to the Acmefyer server.
• HTTP-01 with an existing web server: If a web server already runs on port 80, Acmefyer puts the validation file in its folder, on the server itself or through an agent on another computer.
• DNS-01: Acmefyer briefly creates an entry in your DNS. This needs the credentials for your DNS provider's interface, which you store under Credentials. Acmefyer knows about 190 providers. DNS-01 is needed for wildcard certificates and for servers that cannot be reached from outside.
• TLS-ALPN-01: Like HTTP-01, but over port 443.

DNS on your own network

If your own DNS server answers for the zone differently than the internet does (typical with Active Directory), Acmefyer does not see the validation entry and waits in vain. In that case, choose public DNS servers: in the console window on the DNS tab (key 4) or with the setting server.dns_resolvers.

Renewal

Every hour Acmefyer checks which certificates expire soon and renews them 30 days ahead. If that fails, Acmefyer tries again later, with growing intervals. To renew a certificate by hand, use Renew in the interface or R in the console window.

Deploying certificates

A new certificate is only useful once it arrives on the target system. For this, you add one or more targets to each certificate. After every renewal Acmefyer installs the certificate on all targets again. If a target fails, Acmefyer tries again after 5 minutes, then at growing intervals up to 6 hours.

For each target you choose who runs it: the server or an agent.

On the server only targets run that install nothing on other systems:

• File (PEM) and PFX: Write the certificate as files to a folder, also to a Windows share.
• SSH: Copy the files to a Linux server over SSH, reloading nginx or Apache if you like.
• Webhook: Call an address when there is a new certificate.

Through an agent runs everything that sets something up locally:

• IIS: Install the certificate in Windows and bind it to the website.
• Exchange: Enable the certificate for the chosen Exchange services.
• Windows certificate store: Install the certificate in a store, for example for RDP or SQL Server.
• nginx and Apache: Write the files and reload the web server.
• FortiGate: Install the certificate through the FortiGate's interface. The agent is best placed in the same network as the firewall.
• Own script: Run any command.

Acmefyer stores the passwords and keys of the targets encrypted.

Agents

An agent is a small program on the target system. It checks in with the Acmefyer server regularly, fetches new jobs and runs them. The connection always goes from the agent to the server, never the other way round.

To set up an agent:

1. The server needs HTTPS, see HTTPS for the server.
2. On the server, set a secret enrollment token for agents, agent.enroll_token in config.yaml, for example a long random string. Restart the service.
3. On the target system, put the program file acmefyer-agent in a folder, and next to it a file agent.yaml:

agent:
  server_url: "https://acme.example.com:8443"
  enroll_token: "the same token as on the server"

1. Set up the agent as a service and start it:

.\acmefyer-agent.exe service install
.\acmefyer-agent.exe service start

sudo ./acmefyer-agent service install
sudo ./acmefyer-agent service start

The agent then appears in the interface under Agents. On its first connection it gets an identity of its own from the server (a certificate and a key of its own) and stores it in the folder agent-data. After that it no longer needs the enrollment token. You can remove it from agent.yaml.

Without HTTPS the server refuses agents, and the agent does not connect to an http:// address. For a test setup only, this can be switched off with agent.allow_insecure_http: true, on the server and the agent.

Notifications

Under Notifications you decide who hears about it when a certificate was issued, a renewal fails or a certificate expires soon. E-mail, Microsoft Teams, Telegram, PRTG and webhooks are available. Test checks that a message arrives.

Users and permissions

Besides the local user admin, your colleagues can sign in with their Windows account once you connect Active Directory (or another LDAP server). You set this up under Settings and test it there, too.

Groups in the directory grant the permissions:

• Admin: may do everything, including credentials, agents, notifications and settings.
• Operator: creates certificates and targets, renews and deletes them.
• Viewer: sees everything, changes nothing.

For administrators, a sign-in with a second factor can be switched on, using an authenticator app. All changes are recorded in the Audit log, with time and user.

Forgot the admin password? Stop the service, delete the line local_admin_password_hash in config.yaml and start the service again. Acmefyer then creates a new initial password and shows it in the console window and in the log.

License and activation

Without a license key, Acmefyer manages one domain with one subdomain (or one wildcard certificate) and one agent, so you can try the program. With a license key there are no limits.

• You receive the license key by e-mail right after the purchase. Enter it in the interface under Settings → License, together with the e-mail address you bought it with. Alternatively it goes in config.yaml under license.
• Activation needs a connection from the server to www.wedigo.net, also through a proxy (see Internet access through a proxy). After that Acmefyer checks in there briefly every 30 days. If the connection fails, the license keeps working for up to 60 days.
• A license covers one installation and all updates of the purchased version, for example all 1.x versions. When a new major version comes out, Acmefyer points it out but does not install it by itself.
• If a license ends or a key is invalid, Acmefyer still starts and keeps renewing all existing certificates. Only new ones can then no longer be created.

More on purchase and refunds: Pricing and License terms.

Updates

Acmefyer keeps itself up to date. It regularly checks www.wedigo.net for a new version, verifies that it really comes from us, and installs it.

How this works is set by update.mode:

• auto (default): New versions are installed, and the service restarts briefly afterwards.
• notify: Acmefyer only reports a new version. You install it yourself in the interface under Settings.
• off: No update checks.

With update.window you set a time during which installing is allowed, for example "02:00-05:00".

Updates always stay within your major version, for example 1.x. When a new major version comes out, Acmefyer shows a notice at the top of every page and under Settings at the software update and the license: your license is not valid for the new major version, it needs an upgrade. Your version keeps receiving updates. An administrator can dismiss the notice at the top; it returns with the next major version.

Updates are only installed automatically when Acmefyer runs as a service and may write to its program folder. Started by hand in the console window, it only reports new versions.

Back to the previous version

Acmefyer keeps the previous version. If a new version does not start properly, it goes back to the old one by itself. You can also do this by hand:

.\acmefyer-server.exe rollback
.\acmefyer-server.exe service restart

sudo ./acmefyer-server rollback
sudo ./acmefyer-server service restart

Backup

Back up the server's program folder. What matters:

• config.yaml: your settings and the master key. Without it the database can no longer be read.
• acmefyer.db: all certificates, targets, agents and credentials. It is safest to copy it while the service is stopped.
• the folder data: among other things the certificate authority for the agents. If it is lost, all agents have to enroll again.

On the agents, agent.yaml with the folder agent-data is enough. If the folder is missing, the agent enrolls again with the enrollment token.

Troubleshooting

A certificate is not issued. What exactly went wrong is shown with the certificate in the interface and in the console window on the Logs tab (key 7). Common reasons: port 80 cannot be reached from outside (HTTP-01), the credentials for the DNS provider are wrong, or your own DNS server answers differently than the internet (see DNS on your own network).

Browsers warn about the new certificate. It is probably a test certificate from the staging environment. Create it again with a real certificate authority.

An agent does not show up. Does the server run with HTTPS? Do server_url and the enrollment token match on both sides? Can the target system reach the server on port 8443? The agent writes the reason to its log.

License or updates: no connection to www.wedigo.net. The interface shows the reason under Settings → License. If the server has no direct internet access, check in the log or on the Settings tab of the console window which proxy is used; if there is none, enter it, see Internet access through a proxy. On the Settings tab of the console window, t tests the connection.

Since the proxy is set, a webhook or notification on your own network fails. Add its name to the proxy exceptions (proxy.no_proxy).

The interface only works on the server itself. That is the default. See Access from other computers.

An update is not installed. Does Acmefyer run as a service, and may it write to its folder? A version that was rolled back once is not installed again.

If none of this helps, write to us using the contact form.

Look up

This part is meant for looking things up when you want to set something specific.

Settings

The settings are in the file config.yaml in the program folder, the agent's in agent.yaml. Open them with a text editor. After a change, restart the service. Instead, you can also set every value through an environment variable, shown in the table below the name.

Server

Login

Agent

These values are in agent.yaml on the target system. Only agent.enroll_token and agent.allow_insecure_http also apply on the server.

License

Updates

Proxy

Log and database

Commands

Enter these commands in the console window in the program folder.

Keys in the console window

Interface for your own scripts

Certificates can also be created and queried through an interface (JSON), for example from your own scripts. For this, set a key in server.api_token and send it with every call (Authorization: Bearer <key>). The addresses for agents are used by acmefyer-agent only.