diff options
Diffstat (limited to 'docs/manual/advanced-use')
| -rw-r--r-- | docs/manual/advanced-use/custom-logging.md | 55 | ||||
| -rw-r--r-- | docs/manual/advanced-use/examples/apache.md | 99 | ||||
| -rw-r--r-- | docs/manual/advanced-use/examples/exchange.md | 53 | ||||
| -rw-r--r-- | docs/manual/advanced-use/examples/index.md | 10 | ||||
| -rw-r--r-- | docs/manual/advanced-use/examples/rds.md | 27 | ||||
| -rw-r--r-- | docs/manual/advanced-use/index.md | 76 | ||||
| -rw-r--r-- | docs/manual/advanced-use/load-balancing.md | 33 |
7 files changed, 0 insertions, 353 deletions
diff --git a/docs/manual/advanced-use/custom-logging.md b/docs/manual/advanced-use/custom-logging.md deleted file mode 100644 index 635a2fa..0000000 --- a/docs/manual/advanced-use/custom-logging.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar: manual ---- - -# Custom logging -The program users [Serilog](https://serilog.net/) for logging which is a powerful extensible library. - -## Levels -win-acme uses the following five log levels: - -- `Error` - Logs fatal or dangerous conditions -- `Warning` - Logs minor errors and suspicious conditions -- `Information` - General information about operations -- `Debug` - Additional information that can be useful for troubleshooting -- `Verbose` - Full logging for submitting bug reports - -You can change the log level by adding the following setting: - -`<add key="serilog:minimum-level" value="Verbose" />` - -## Included sinks -- The default sink logs to the console window to provide real time insights. -- The `event` sink writes to the Windows Event Viewer includes `Error`, `Warning` and selected `Information` messages. -- The `disk` sink writes rolling log files to `%programdata%\win-acme\log` - (that path can be changed in [settings.json](/win-acme/reference/settings)) - -## Custom sinks -There are many types of output channels called [sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks) for all -kinds of different databases, file formats and services. - -### Example (Seq) - -- Download `Serilog.Sinks.PeriodicBatching.dll` and `Serilog.Sinks.Seq.dll` from NuGet. These files can be found -[here](https://www.nuget.org/packages/Serilog.Sinks.PeriodicBatching) and -[here](https://www.nuget.org/packages/Serilog.Sinks.Seq), respectively. -- Configure the sink in a file called `serilog.json` according to the specification [here](https://github.com/serilog/serilog-settings-configuration). - -### Example - -The follow piece of code in `serilog.json` adds the process ID to the output of the file log. - -```json -{ - "disk": { - "WriteTo": [ - { - "Name": "File", - "Args": { - "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [PID:{ProcessId}] {Message:lj}{NewLine}{Exception}" - } - } - ] - } -} -```
\ No newline at end of file diff --git a/docs/manual/advanced-use/examples/apache.md b/docs/manual/advanced-use/examples/apache.md deleted file mode 100644 index b72de7a..0000000 --- a/docs/manual/advanced-use/examples/apache.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -sidebar: manual ---- - -# Apache -To get the certificate in the correct format for Apache (i.e. `.pem` files), you have to active -the [PemFiles plugin](/win-acme/reference/plugins/store/pemfiles) for each of your renewals. -For **new** renewals this can be done either from the command line with `--store pemfiles` or -from the main menu with the `M` option, where it will be posed as a question ("How would you -like to store this certificate?"). - -Existing renewals that are set up without the PemFiles plugin (which unfortunately includes -those [imported](/win-acme/manual/upgrading/to-v2.0.0) from 1.9.x) cannot be modified with a -command line switch or settings change. You will have to re-create them one by one, or manually -modify the `.json` files on disk. - -## Getting the certificate in .pem format - -### Interactive -- Choose `M` in the main menu (create with full options) -- Choose "Manually input host names" as target -- Input the domain name(s) -- Choose or accept the friendly name -- Pick a validation method. Most common would be to save to a local path -- Pick your key type -- Now the critical part: at "How would you like to store this certificate?" pick `Write .pem files to folder (Apache, nginx, etc.)` -- And so on... - -### Unattended -`wacs.exe --target manual --host www.example.com --validation filesystem --webroot "C:\htdocs\www\example.com" --store pemfiles --pemfilespath C:\apache-certs` - -### Pro tip -If you don't want to have to specify the path for the `.pem` files each time, you can -edit `settings.json` in the program directory and set the `DefaultPemFilesPath` -option. - -## Configuring Apache -To use certificates obtained with the help of WACS with the Apache 2.4 server, you need -to make settings in `Apache24\conf\extra\httpd-vhosts.conf` file; you could also make -these changes in the `\Apache24\conf\extra\httpd-ssl.conf` file as well instead if -you so wish: - -``` -Define CERTROOT "C:/apache-certs" -Define SITEROOT "C:/htdocs/www" -.... -<VirtualHost *:443> - ServerName www.example.com - DocumentRoot "${SITEROOT}/example.com" -.... - SSLEngine on - SSLCertificateFile "${CERTROOT}/example.com-chain.pem" - SSLCertificateKeyFile "${CERTROOT}/example.com-key.pem" -</VirtualHost> -``` - -Obviously replace `example.com` with your actual domain name your siteroot to -where you're hosting your files. - -### Enable SSL -Do not forget to uncomment `LoadModule ssl_module modules/mod_ssl.so` in `Apache24\conf\httpd.conf` -file if it's not already uncommented. You also need to add `Listen 443` or `Listen 80 443`. - -### Not for XAMPP uses -You don't need the `/example.com` at the end after `"${SITEROOT}"` so it -should just read as: `DocumentRoot "${SITEROOT}"` for that one line or else -(at least according to my case), would result in an object not found 404 error -when you visit your domain page. - -Also, according to Apache standards, backslash means escaping characters so if you wanted to -use backslash as a way for defining directories, then you're supposed to use another one -so it looks like `C:\\XAMPP\\Apache\\somestuff` but apparently the developers have modded -it so that it doesn't really matter if you double slash or not or use forward slash instead -of a single back slash - they all work the same regardless, at least as of version -3.2.2 of XAMPP. - -## Addendum -If you want to use your own folder to store certificates, you can use this cmd script is -for copying (for example, with name `installcert.cmd`): - -``` -@echo off -if "%~1" == "" exit -if not exist "%2" md "%2" >nul -set certlist=%3-chain.pem,%3-key.pem -echo Script running... -for %%a in (%certlist%) do copy /y "%ProgramData%\win-acme\%1\%%a" "%2\" >nul && echo. [INFO] Install %%a to Certificate Store in %2... OK || echo. [WARN] Install certificate %%a fieled! -echo. [INFO] Restarting service... -C:\Apache24\bin\httpd.exe -k restart -echo. [INFO] Service restarted. -echo. [INFO] Script finished. -``` -This script is called with parameters: -`LEWSuriDirectory CertFolder DomainName` - -For example: -`wacs.exe --target manual --host www.example.com --webroot "C:\htdocs\www\example.com" --validation filesystem --script "installcert.cmd" --scriptparameters "acme-v02.api.letsencrypt.org C:\cert www.example.com"` - -Also you must specify a new path to the folder with certificates in your `httpd-vhosts.conf`.
\ No newline at end of file diff --git a/docs/manual/advanced-use/examples/exchange.md b/docs/manual/advanced-use/examples/exchange.md deleted file mode 100644 index 7bb444c..0000000 --- a/docs/manual/advanced-use/examples/exchange.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar: manual ---- - -# Microsoft Exchange -Choose the domains that you want to generate the certificate for. Note that Let's Encrypt only -issues certificates to public domains, that means no Active Directory server names or domain suffixes -that are only known inside of your intranet can be used. You can specify a maximum of 100 domains -in a certificate. - -Assumptions made in this example: - -- We want to generate the certificate for three domains - - mail.example.com - - webmail.example.com - - autodiscover.example.com -- mail.example.com will be the common name, hence we put it first -- OWA is running in the Default Web Site of IIS with Site Id `1`. -- We want to enable the certificate for SMTP and IMAP - -## Interactive -- Create certificate with full options -- Manually input host names -- [http-01] Self-host verification files -- Create or update https bindings in IIS -- Would you like to add another installer step? (y/n): Y -- Run a custom script -- Would you like to add another installer step? (y/n): N -- Choose site to create new bindings: Default Web Site (or where ever OWA is at) -- Enter the path to the script that you want to run after renewal: `./Scripts/ImportExchange.ps1` -- Enter the parameter format string for the script: `'{CertThumbprint}' 'IIS,SMTP,IMAP' 1 '{CacheFile}' '{CachePassword}' '{CertFriendlyName}'` - -## Unattended -- Without Central Certificate Store - `wacs.exe --target manual --host mail.example.com,webmail.example.com,autodiscover.example.com --certificatestore My --acl-fullcontrol "network service,administrators" --installation iis,script --installationsiteid 1 --script "./Scripts/ImportExchange.ps1" --scriptparameters "'{CertThumbprint}' 'IIS,SMTP,IMAP' 1 '{CacheFile}' '{CachePassword}' '{CertFriendlyName}'"` - -- With Central Certificate Store -`wacs.exe --target manual --host mail.example.com,webmail.example.com,autodiscover.example.com --store centralssl --centralsslstore "C:\Central SSL" --installation iis,script --installationsiteid 1 --script "./Scripts/ImportExchange.ps1" --scriptparameters "'{CertThumbprint}' 'IIS,SMTP,IMAP' 1 '{CacheFile}' '{CachePassword}' '{CertFriendlyName}'"` - -## Verification -To make sure all is working properly, I'd encourage you to use the -[Microsoft's Remote Connectivity Analyzer](https://testconnectivity.microsoft.com/). -The Autodiscover and ActiveSync Autodiscover tests are really useful for testing this out. -With Outlook 2016 requiring the use of [Autodiscover to connect to Exchange](http://blogs.technet.com/b/exchange/archive/2015/11/19/outlook-2016-what-exchange-admins-need-to-know.aspx), -verifying that this works properly is an important step is making sure your environment is setup correctly. - -## References -- [Assign certificates to Exchange services](https://technet.microsoft.com/en-us/library/dd351257%28v=exchg.160%29.aspx) -- [Import certificates into Exchange](https://technet.microsoft.com/en-us/library/bb124424(v=exchg.160).aspx) -- [Add MIME Type](https://support.microsoft.com/en-us/kb/326965) -- [Namespace planning in Exchange 2016](http://blogs.technet.com/b/exchange/archive/2015/10/06/namespace-planning-in-exchange-2016.aspx) -- [Exchange Server 2016 Client Access Namespace configuration](http://exchangeserverpro.com/exchange-server-2016-client-access-namespace-configuration/) -- [Install Exchange 2016 in your lab](https://supertekboy.com/2015/09/22/install-exchange-2016-in-your-lab-part-5/)
\ No newline at end of file diff --git a/docs/manual/advanced-use/examples/index.md b/docs/manual/advanced-use/examples/index.md deleted file mode 100644 index 949316d..0000000 --- a/docs/manual/advanced-use/examples/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -sidebar: manual ---- -# Examples -There are some [example scripts](https://github.com/PKISharp/win-acme/tree/master/dist/Scripts) -bundled with win-acme releases as a reference and inspiration for people looking to handle custom -[installation](/win-acme/reference/plugins/installation/script) or -[DNS validation](/win-acme/reference/plugins/validation/dns/script). - -The scripts are provided as-is. Caution is advised before running them on production systems.
\ No newline at end of file diff --git a/docs/manual/advanced-use/examples/rds.md b/docs/manual/advanced-use/examples/rds.md deleted file mode 100644 index 5eb51ae..0000000 --- a/docs/manual/advanced-use/examples/rds.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -sidebar: manual ---- - -# Remote Desktop Services -How to generate a Certificate for Microsoft Remote Desktop Servers - -## Running the client -Assuming you've a simple all in one Remote Desktop Server setup with the roles RD Gateway, RD Connection Broker -and RD Web Access, you have to import the certificate into the IIS site and additionally configure it for the -installed RD roles. For IIS the standard plugin is used, for the RD roles, the included `ImportRDSFull.ps1` is -used. - -## Configuration -In order for this script to work, the private key of the certificate needs to be marked as exportable. -Set `PrivateKeyExportable` in `settings.json` to `true`. - -The script accepts two parameters: CertThumbprint and RDCB. RDCB specifies the Remote Desktop Connection Broker -(RD Connection Broker) server for a Remote Desktop deployment. If you don't specify a value, the script uses the local -computer's fully qualified domain name (FQDN). - -## Unattended -- When specific domain names are configured in the IIS bindings, we can use them automatically -`wacs.exe --target iis --siteid 1 --certificatestore My --installation iis,script --script "Scripts\ImportRDSFull.ps1" --scriptparameters "{CertThumbprint}"` - -- When only blank/catch-all binding are configured in IIS, we have to be explicit about the domain name(s) that we want -`wacs.exe --target manual --hostname rds.example.com --certificatestore My --installation iis,script --installationsiteid 1 --script "Scripts\ImportRDSFull.ps1" --scriptparameters "{CertThumbprint}"`
\ No newline at end of file diff --git a/docs/manual/advanced-use/index.md b/docs/manual/advanced-use/index.md deleted file mode 100644 index c0de3c9..0000000 --- a/docs/manual/advanced-use/index.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -sidebar: manual ---- - -# Advanced use -The simple mode works well for the most common use case, but there are many -reasons to go for full options mode. For example: -- You don't use IIS -- You need to use [DNS validation](/win-acme/reference/plugins/validation/dns/) because - - You are requesting a wildcard certificate - - Port 80 is blocked on your network -- You are not running the program from your web server -- You are load balancing -- You need to run a script after each renewal, e.g. for [Exchange](/win-acme/manual/advanced-use/examples/exchange) -- etc. - -## Interactive -This describes the basic steps of an full options rewenal from the interactive menu. It touches -on concepts described [here](/win-acme/reference/plugins/), because this mode of operation -exposes more of the internal logic of the program to use to your advantage. Don't worry if -this seems overwhelming: most options have sensible defaults that you can select by just -pressing `<Enter>` in response to a question. - -- Choose `M` in the main menu to create a new certificate in full options mode -- Choose a [target plugin](/win-acme/reference/plugins/target/) that will be used - to determine for which domain(s) the certificate should be issued. -- Choose a [validation plugin](/win-acme/reference/plugins/validation/) to pick the - method that will be used to prove ownership of your domain(s) to the ACME server. -- Pick between RSA and EC private keys, which are both [plugins](/win-acme/reference/plugins/csr/) - used to generate a certificate signing request (CSR). -- One or more [store plugins](/win-acme/reference/plugins/store/) must be selected to save - the certificate. For Apache, nginx and others web servers the `PemFiles` plugin is commonly - chosen. -- One or more [installation plugins](/win-acme/reference/plugins/installation/) can be selected - to run after the certificate has been requested. The standard IIS option from simple mode - is of course available, but also the powerful [script installer](/win-acme/reference/plugins/installation/script). -- A registration with the ACME server is created, if it doesn't already exist. You will be - asked to agree to the terms of service and to provide an email address that the server - administrators can use to contact you. -- The program negotiates with ACME server to try and prove your ownership of the domain(s) that you want to - create the certificate for, using the method of your choice. Getting validation right is often the most tricky - part of getting an ACME certificate. If there are problems please check out some - [common issues](/win-acme/manual/validation-problems). -- After validating the domains, a certificate signing request is prepared according to - your specifications. -- The CSR is submitted to the ACME server and the signed response is saved according to your wishes. -- The program runs the requested installation steps. -- The program remembers all choices that you made while creating the certificate and applies them -for each subsequent [renewal](/win-acme/manual/automatic-renewal). - -## Unattended -By providing the right [command line arguments](/win-acme/reference/cli) at start up you can do -everything that is possible in interactive mode (and more) without having to jump through the menu's. -This is great way to make win-acme part of a larger automation workflow. - -### Examples -The `--target` switch, used to select a [target plugin](/win-acme/reference/plugins/target/), -triggers the unattended creation of new certificate. - -- `--target manual` - selects the [manual plugin](/win-acme/reference/plugins/target/manual). -- `--target iis` - selects the [iis plugin](/win-acme/reference/plugins/target/iis). - -Each plugin has their own inputs which it needs to generate the certificate, for example: - -```wacs.exe --target manual --host www.domain.com --webroot C:\sites\wwwroot``` -```wacs.exe --target iis --siteid 1 --excludebindings exclude.me``` - -There are some other parameters needed for first-time unattended use (e.g. on a clean server) -to create the Let's Encrypt registration automatically (```--emailaddress myaddress@example.com --accepttos```). -So a full command line to create a certificate for IIS site 1 on a clean server (except for -the 'exclude.me' binding) would look like this: - -```wacs.exe --target iis --siteid 1 --excludebindings exclude.me --emailaddress myaddress@example.com --accepttos``` - -#### More examples -Some application-specific examples are available [here](/win-acme/manual/advanced-use/examples).
\ No newline at end of file diff --git a/docs/manual/advanced-use/load-balancing.md b/docs/manual/advanced-use/load-balancing.md deleted file mode 100644 index 4121a54..0000000 --- a/docs/manual/advanced-use/load-balancing.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -sidebar: manual ---- - -# Load balancing -Some pointers on win-acme and load balancing. - -## Sharing certificates between servers -It really depends if you're using a separate appliance to offload HTTPS or if it's -handled by the servers in the pool themselves. In the latter case you should probably -use the [Central Certificate Store](https://blogs.msdn.microsoft.com/kaushal/2012/10/11/central-certificate-store-ccs-with-iis-8-windows-server-2012/) -feature of IIS. Instructions on how to configure win-acme to use it can be found -[here](/win-acme/reference/plugins/store/centralssl). - -## Scheduled task -- You can have a single server act as a renewal server running win-acme. That means it's a single - point of failure, but only a minor one, because certificates only need to be renewed once every - three months. -- To distribute the task of renewing, you should point the `ConfigurationPath` in the `settings.json` - of win-acme to somewhere on your SAN, so that any member of the pool can potentially renew the - certificates. -- You can configure the Scheduled Task on different machines at different times, e.g. one at 4:00 am, - the next at 5:00 am, etc. Then you can be sure that they will not run at the same time and the first - one that succeeds handles everything. -- If you're building an actual cluster, you can use a Clustered Task instead of a regular Scheduled Task. - -## Encryption -The encryption for the config files will have to be disabled via `settings.json` so that all machines -in the cluster can read the passwords. - -## Appliance -If you are using an appliance then you have to use their API and call into that from a `.bat`/`.ps1`/`.exe` -using an [installation script](/win-acme/reference/plugins/installation).
\ No newline at end of file |