Merged docker/README.md into docs (#103)

* Merged docker/README.md into docs

* Minor reformulations
Added references

* Moved docker section one up, because they are not really start parameters

* Fix links

* Moved the supported products section into documentation, as it does not fit the usage topic
This commit is contained in:
Simonmicro 2020-10-16 22:58:56 +02:00 committed by GitHub
parent de1c115967
commit c979f42da9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 103 additions and 122 deletions

View File

@ -1,116 +0,0 @@
# Usage
```
docker run -it -d --name py3-kms \
-p 8080:8080 \
-p 1688:1688 \
-e IP=0.0.0.0 \
-e PORT=1688 \
-e SQLITE=true \
-e HWID=RANDOM \
-e LOGLEVEL=INFO \
-e LOGSIZE=2 \
-e LOGFILE=/var/log/pykms_logserver.log \
-v /etc/localtime:/etc/localtime:ro \
-v /var/log:/var/log:rw \
--restart unless-stopped pykmsorg/py-kms:[TAG]
```
_Make sure to insert at `[TAG]` your wanted edition! The default is `latest`, which does not include SQLite support. For all available tag check [this](https://hub.docker.com/r/pykmsorg/py-kms/tags)._
Therefore you can omit the `-e SQLITE=...` and `-p 8080:8080` option if you plan to use the `minimal` or `latest` image.
## Docker-compose
You can use docker-compose instead of Dockerfile. The following compose file will deploy `latest` image into your local directory.
```
version: '3'
services:
kms:
image: pykmsorg/py-kms:latest
ports:
- 1688:1688
environment:
- IP=0.0.0.0
- SQLITE=true
- HWID=RANDOM
- LOGLEVEL=INFO
- LOGSIZE=2
- LOGFILE=/var/log/pykms_logserver.log
restart: always
volumes:
- /etc/localtime:/etc/localtime:ro
- ./:/var/log:rw
```
# Sqlite-web
A web-based SQLite database browser written in Python.
Start on http://example.com:8080/ in read-only mode for _pykms_database.db_.
# Options
```
# EN: Variables
# RU: Переменные
# EN: IP-address
# RU: IP-адрес
ENV IP 0.0.0.0
# The IP address to listen on. The default is "0.0.0.0" (all interfaces).
# EN: TCP-port
# RU: TCP-порт
ENV PORT 1688
# The network port to listen on. The default is "1688".
# EN: ePID
# RU: ePID
ENV EPID ""
# Use this flag to manually specify an ePID to use. If no ePID is specified, a random ePID will be generated.
# EN: lcid
# RU: lcid
ENV LCID 1033
# Use this flag to manually specify an LCID for use with randomly generated ePIDs. Default is 1033 (en-us).
# EN: the current client count
# RU: текущий счётчик запросов на активацию продуктов от Microsoft
ENV CLIENT_COUNT 26
# Use this flag to specify the current client count. Default is 26.
# A number >=25 is required to enable activation of client OSes; for server OSes and Office >=5.
# EN: the activation interval (in minutes)
# RU: интервал активации (в минутах)
ENV ACTIVATION_INTERVAL 120
# Use this flag to specify the activation interval (in minutes). Default is 120 minutes (2 hours).
# EN: the renewal interval (in minutes)
# RU: интервал обновления (в минутах)
ENV RENEWAL_INTERVAL 10080
# Use this flag to specify the renewal interval (in minutes). Default is 10080 minutes (7 days).
# EN: Use SQLITE
# RU: Использовать РСУБД SQLITE
ENV SQLITE false
# Use this flag to store request information from unique clients in an SQLite database.
# EN: hwid
# RU: hwid
ENV HWID 364F463A8863D35F
# Use this flag to specify a HWID.
# The HWID must be an 16-character string of hex characters.
# The default is "364F463A8863D35F" or type "RANDOM" to auto generate the HWID.
# EN: log level ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
# RU: Уровень логирования ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
ENV LOGLEVEL ERROR
# Use this flag to set a Loglevel. The default is "ERROR".
# EN: log file
# RU: Лог-файл
ENV LOGFILE /var/log/pykms_logserver.log
# Use this flag to set an output Logfile. The default is "/var/log/pykms_logserver.log".
# EN: log file size in MB
# RU: Максимальный размер Лог-файл в мегабайтах
ENV LOGSIZE ""
# Use this flag to set a maximum size (in MB) to the output log file. Deactivated by default.
```

View File

@ -324,6 +324,11 @@ Where command line options are:
</tbody>
</table>
## Supported Products
Note that it is possible to activate all versions in the VL (Volume License) channel, so long as you provide the proper key to let Windows know that it should be activating against a KMS server. KMS activation can't be used for
Retail channel products, however you can install a VL product key specific to your edition of Windows even if it was installed as Retail. This effectively converts Retail installation to VL channel and will allow you to activate
from a KMS server. **However, this is not valid for Office's products**, so Office, Project and Visio must be always volume license versions. Newer version may work as long as the KMS protocol does not change...
## Further References
* <sup>[1]</sup> https://forums.mydigitallife.net/threads/emulated-kms-servers-on-non-windows-platforms.50234
* <sup>[2]</sup> https://forums.mydigitallife.net/threads/discussion-microsoft-office-2019.75232

View File

@ -24,7 +24,7 @@ latest version you should check something like [watchtower](https://github.com/c
There are currently three tags of the image available (select one just by appending `:<tag>` to the image from above):
* `latest`, currently the same like `minimal`.
* `minimal`, which is based on the python3 minimal configuration of py-kms. _This tag does NOT include `sqlite` support !_
* `python3`, which is fully configurable and equipped with `sqlite` support and a web interface for management.
* `python3`, which is fully configurable and equipped with `sqlite` support and a web interface (make sure to expose port 8080) for management.
#### Architectures
There are currently the following architectures available (if you need an other, feel free to open an issue):
@ -35,6 +35,48 @@ There are currently the following architectures available (if you need an other,
_Please note that any architecture other than the classic `amd64` is slightly bigger (~4 MB), caused by the use of qemu during building._
#### Docker Compose
You can use `docker-compose` instead of building and running the Dockerfile, so you do not need to respecify your settings again and again. The following Docker Compose file will deploy the `latest` image with the log into your local directory.
```yaml
version: '3'
services:
kms:
image: pykmsorg/py-kms:latest
ports:
- 1688:1688
environment:
- IP=0.0.0.0
- SQLITE=true
- HWID=RANDOM
- LOGLEVEL=INFO
- LOGSIZE=2
- LOGFILE=/var/log/pykms_logserver.log
restart: always
volumes:
- /etc/localtime:/etc/localtime:ro
- ./:/var/log:rw
```
#### Parameters
Below is a fully expanded run command, detailing all the different supported environment variables to set. For further reference see the [start parameters](Usage.html#docker-environment) for the docker environment.
```bash
docker run -it -d --name py3-kms \
-p 8080:8080 \
-p 1688:1688 \
-e IP=0.0.0.0 \
-e PORT=1688 \
-e SQLITE=true \
-e HWID=RANDOM \
-e LOGLEVEL=INFO \
-e LOGSIZE=2 \
-e LOGFILE=/var/log/pykms_logserver.log \
-v /etc/localtime:/etc/localtime:ro \
-v /var/log:/var/log:rw \
--restart unless-stopped pykmsorg/py-kms:[TAG]
```
You can omit the `-e SQLITE=...` and `-p 8080:8080` option if you plan to use the `minimal` or `latest` image, which does not include the respective module support.
### Systemd
If you are running a Linux distro using `systemd`, create the file: `sudo nano /etc/systemd/system/py3-kms.service`, then add the following (change it where needed) and save:
```systemd

View File

@ -301,6 +301,61 @@ You can enable same _pykms_Server.py_ suboptions of `-F`.
-S or --logsize <MAXSIZE>
> Use this flag to set a maximum size (in MB) to the output log file. Deactivated by default.
## Docker Environment
This are the currently used `ENV` statements from the Dockerfile(s). For further references what exactly the parameters mean, please see the start parameters for the [server](Usage.html#pykms-server-py).
```
# IP-address
# The IP address to listen on. The default is "0.0.0.0" (all interfaces).
ENV IP 0.0.0.0
# TCP-port
# The network port to listen on. The default is "1688".
ENV PORT 1688
# ePID
# Use this flag to manually specify an ePID to use. If no ePID is specified, a random ePID will be generated.
ENV EPID ""
# lcid
# Use this flag to manually specify an LCID for use with randomly generated ePIDs. Default is 1033 (en-us).
ENV LCID 1033
# The current client count
# Use this flag to specify the current client count. Default is 26.
# A number >=25 is required to enable activation of client OSes; for server OSes and Office >=5.
ENV CLIENT_COUNT 26
# The activation interval (in minutes)
# Use this flag to specify the activation interval (in minutes). Default is 120 minutes (2 hours).
ENV ACTIVATION_INTERVAL 120
# The renewal interval (in minutes)
# Use this flag to specify the renewal interval (in minutes). Default is 10080 minutes (7 days).
ENV RENEWAL_INTERVAL 10080
# Use SQLITE
# Use this flag to store request information from unique clients in an SQLite database.
ENV SQLITE false
# hwid
# Use this flag to specify a HWID.
# The HWID must be an 16-character string of hex characters.
# The default is "364F463A8863D35F" or type "RANDOM" to auto generate the HWID.
ENV HWID 364F463A8863D35F
# log level ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG")
# Use this flag to set a Loglevel. The default is "ERROR".
ENV LOGLEVEL ERROR
# Log file
# Use this flag to set an output Logfile. The default is "/var/log/pykms_logserver.log".
ENV LOGFILE /var/log/pykms_logserver.log
# Log file size in MB
# Use this flag to set a maximum size (in MB) to the output log file. Deactivated by default.
ENV LOGSIZE ""
```
## Activation Procedure
The product asks for a key during installation, so it needs you to enter the GVLK. Then the user can set connection parameters, while KMS server must already be running on server machine. Finally with specific commands, activation occurs automatically and can be extended later every time for another 180 (or 30 or 45) days.
@ -344,8 +399,3 @@ Note that youll have to install a volume license (VL) version of Office. Offi
6. Set the connection parameter KMS server port.
7. Activate installed Office product key.
8. View license informations (in my case product is now licensed and remaining grace 180 days as expected).
## Supported Products
Note that it is possible to activate all versions in the VL (Volume License) channel, so long as you provide the proper key to let Windows know that it should be activating against a KMS server. KMS activation can't be used for
Retail channel products, however you can install a VL product key specific to your edition of Windows even if it was installed as Retail. This effectively converts Retail installation to VL channel and will allow you to activate
from a KMS server. **However, this is not valid for Office's products**, so Office, Project and Visio must be always volume license versions. Newer version may work as long as the KMS protocol does not change...