Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve Documentation #339

Merged
10 commits merged into from
Jun 2, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 24 additions & 23 deletions docs/_docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,14 @@ redirect_from: /docs/configuration.html
---

{% comment %}disable jekyll-titles-from-headings{% endcomment %}

# Default Properties

***

MQTT CLI uses some default values which can be overwritten.
MQTT CLI stores the default values in a properties file which is located under the user home directory of your OS under `$HOME/.mqtt-cli/config.properties`.
MQTT CLI stores the default values in a properties file which is located under the user home directory of your OS
under `$HOME/.mqtt-cli/config.properties`.

On the first successful execution of the CLI this file will be generated and will look like the following example:

Expand All @@ -25,25 +28,23 @@ logfile.path=/Users/tseeberg/.mqtt-cli/logs/
```
This conversation was marked as resolved.
Show resolved Hide resolved

A properties file lists all the properties as key-value pairs.
Therefore you have to specify the values to the following keys if you want to overwrite the given default values.


|Key | Explanation | Default |
| ------- | -------------- | ------------------------- |
| ``mqtt.host`` | The default address of the broker which the client will connect to.| ``localhost``
| ``mqtt.port`` | The default port of the broker which the client will connect to.| ``1883``
| ``mqtt.version``| The default mqtt version witch client will use. | ``5``
| ``client.id.prefix`` | The default client prefix which will be prepended to the randomly generated client names. | ``mqttClient``
| ``client.id.length`` | The length of the randomly generated client id if none is given | ``8``
| ``ws.path`` | The default WebSocket path on a broker | ``/mqtt``
| ``auth.username`` | The default username to use for authentication |
| ``auth.password`` | The default password to use for authentication |
| ``auth.password.env`` | The default environment variable to read the password from |
| ``auth.password.file`` | The default file to read the password from |
| ``auth.client.cert`` | The path to the default client certificate |
| ``auth.client.key`` | The path to the default client key corresponding to the certificate |
| ``auth.server.cafile`` | The path to the default server certificate |
| ``client.subscribe.output``| The default filepath to which all the received publishes of a subscribed client will be written to. See `sub -of` option |
| ``logfile.level``| The default debug level for the logfile which may be one of the following values: ``{INFO | DEBUG | TRACE}`` | ``DEBUG``
| ``logfile.path`` | The default path to the logfile directory to which all the logs will be written | `~/.mqtt-cli/logs`

Therefore, you have to specify the values to the following keys if you want to overwrite the given default values.

| Key | Explanation | Default |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------|--------------------|
| `mqtt.host` | The default address of the broker which the client will connect to. | `localhost` |
This conversation was marked as resolved.
Show resolved Hide resolved
| `mqtt.port` | The default port of the broker which the client will connect to. | `1883` |
| `mqtt.version` | The default mqtt version witch client will use. | `5` |
This conversation was marked as resolved.
Show resolved Hide resolved
| `client.id.prefix` | The default client prefix which will be prepended to the randomly generated client names. | `mqttClient` |
| `client.id.length` | The length of the randomly generated client id if none is given | `8` |
This conversation was marked as resolved.
Show resolved Hide resolved
| `ws.path` | The default WebSocket path on a broker | `/mqtt` |
| `auth.username` | The default username to use for authentication | |
| `auth.password` | The default password to use for authentication | |
| `auth.password.env` | The default environment variable to read the password from | |
| `auth.password.file` | The default file to read the password from | |
| `auth.client.cert` | The path to the default client certificate | |
| `auth.client.key` | The path to the default client key corresponding to the certificate | |
| `auth.server.cafile` | The path to the default server certificate | |
| `client.subscribe.output` | The default filepath to which all the received publishes of a subscribed client will be written to. See `sub -of` option | |
| `logfile.level` | The default debug level for the logfile which may be one of the following values: `{INFO \| DEBUG \| TRACE}` | `DEBUG` |
| `logfile.path` | The default path to the logfile directory to which all the logs will be written | `~/.mqtt-cli/logs` |
62 changes: 22 additions & 40 deletions docs/_docs/hivemq.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ redirect_from: /docs/hivemq.html
---

# HiveMQ
***

The HiveMQ command line argument offers various HiveMQ specific commands.
***

The HiveMQ command line argument offers various HiveMQ specific commands.

```
$ mqtt hivemq

Usage: hivemq [-hV] [COMMAND]
Usage: mqtt hivemq [-hV] [COMMAND]

HiveMQ Command Line Interpreter.

Expand All @@ -21,66 +21,48 @@ Options:
-V, --version Print version information and exit.

Commands:
export Exports the specified details from a HiveMQ API endpoint

export Exports the specified details from HiveMQ
```

***

## Export

The export command of the HiveMQ command line offers a set of commands to export various resources from a HiveMQ API endpoint.
The export command of the HiveMQ command line offers a set of commands to export various resources from a HiveMQ API
endpoint.

```
$ mqtt hivemq export

Usage: hivemq export [-hV] [COMMAND]
Usage: mqtt hivemq export [-hV] [COMMAND]

Exports the specified details from a HiveMQ API endpoint
Exports the specified details from HiveMQ

Options:
-h, --help Show this help message and exit.
-V, --version Print version information and exit.

Commands:
clients Export HiveMQ client details
```
### Synopis

```
mqtt hivemq export [COMMAND] [-hlV]
[-f=<file>]
[--format=<format>]
[-r=<rateLimit>]
[-url=<url>]
[--csvEscChar=<csvEscapeChar>]
[--csvLineEndChar=<csvLineEndCharacter>]
[--csvQuoteChar=<csvQuoteCharacter>]
[--csvSeparator=<csvSeparator>]

Commands:
clients Export HiveMQ client details
```

***

### Options

|Option |Long Version | Explanation | Default|
|---------|----------------|-----------------------------------------------------|---------|
| ``-url`` | | The URL of the HiveMQ API endpoint. | ``http://localhost:8888``
| ``-f``| ``--file`` | The file to write the output to. | If no file is specified a new file is created in the current directory.
| ``-r``| ``--rate`` | The rate limit of the rest calls to the HiveMQ API endpoint in requests per second. | ``1500``
| | ``--format`` | The export output format. (Currently supported formats [``csv``]) | ``csv``
| | `` --csvSeparator=`` | The separator for csv export. | ``,``
| | `` --csvQuoteChar`` | The quote character for csv export. | ``"``
| | `` --csvEscChar`` | The escape character for csv export. | ``"``
| | `` --csvLineEndChar`` | The line-end character for csv export. | ``\n``
| ``-l`` | | Log to ~./mqtt.cli/logs (Configurable through ~/.mqtt-cli/config.properties) | ``false``
| Option | Long Version | Explanation | Default |
|--------|---------------------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `-url` | | The URL of the HiveMQ API endpoint. | `http://localhost:8888` |
| `-f` | `--file` | The file to write the output to. | If no file is specified a new file is created in the current directory. |
| `-r` | `--rate` | The rate limit of the rest calls to the HiveMQ API endpoint in requests per second. | `1500` |
| | `--format` | The export output format. (Currently supported formats [`csv`]) | `csv` |
| | ` --csvSeparator=` | The separator for csv export. | `,` |
| | ` --csvQuoteChar` | The quote character for csv export. | `"` |
| | ` --csvEscChar` | The escape character for csv export. | `"` |
| | ` --csvLineEndChar` | The line-end character for csv export. | `\n` |
| `-l` | | Log to ~./mqtt.cli/logs (Configurable through ~/.mqtt-cli/config.properties) | `false` |

### Export client details

Export client details from a HiveMQ node via the `export clients` command.
Export client details from a HiveMQ node via the `export clients` command.

```
$ mqtt hivemq export clients
Expand All @@ -89,5 +71,5 @@ Exporting client details: ...
Successfully exported x client details to hivemq_client_details_2020-07-30-11:06:24.csv
```

> **NOTE**: The execution of this command may take a while. Expect an export of 100.000 client details to take at least several minutes depending on the chosen rate limit.

> **NOTE**: The execution of this command may take a while. Expect an export of 100.000 client details to take at least
> several minutes depending on the chosen rate limit.
40 changes: 27 additions & 13 deletions docs/_docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
---
nav_order: 2
redirect_from:
- /docs/installation/packages.html
- /docs/installation.html
- /docs/installation/packages.html
- /docs/installation.html
---

# Installation

***

## Prerequisites

At least Java 8 is required to run MQTT CLI.

The CLI is implemented with [Java 11](https://adoptium.net/?variant=openjdk11) which is the preferred version to run this project.
The CLI is implemented with [Java 11](https://www.azul.com/downloads/?version=java-11-lts&package=jdk#zulu) which is the
preferred version to run this project.

***

## Docker

Expand All @@ -24,22 +28,30 @@ docker run hivemq/mqtt-cli <your-command>
```

To start the Shell-Mode of the CLI you need to add the `-it` flags to the docker-command:

```
docker run -it hivemq/mqtt-cli shell
```

***

## Homebrew
For **Mac OS X** and **Linux** systems use **[Homebrew](https://brew.sh/)** to install MQTT CLI via the **[MQTT CLI Tap](https://github.com/hivemq/homebrew-mqtt-cli)**.

For **Mac OS X** and **Linux** systems use **[Homebrew](https://brew.sh/)** to install MQTT CLI via the *
*[MQTT CLI Tap](https://github.com/hivemq/homebrew-mqtt-cli)**.

```
$ brew install hivemq/mqtt-cli/mqtt-cli
```

> **NOTE**: If you encounter an error like `Java 1.8+ is required to install this formula` please install a java version
> higher than 1.8.
> You can use `brew install --cask zulu` to install the latest release of Azul Zulu OpenJDK.

> **NOTE**: If you encounter an error like `Java 1.8+ is required to install this formula` please install a java version higher than 1.8.
> You can use `brew cask install adoptopenjdk` to install the latest release of adoptopenjdk.

> **NOTE**: As latency-issues may slow down the CLI under **Mac OS X** please verify that you have the entry ``127.0.0.1 localhost your-pc-name`` specified under ``/etc/hosts``.
> You can use ``sudo sh -c "echo 127.0.0.1 localhost $(hostname) >> /etc/hosts"`` to append this configuration to your hosts file.
> **NOTE**: As latency-issues may slow down the CLI under **Mac OS X** please verify that you have the
> entry `127.0.0.1 localhost your-pc-name` specified under `/etc/hosts`.
> You can use `sudo sh -c "echo 127.0.0.1 localhost $(hostname) >> /etc/hosts"` to append this configuration to your
> hosts file.

***

Expand All @@ -56,7 +68,8 @@ To quick start the shell simply double-click the `mqtt-cli-shell.cmd` file.

## Debian Package

If you are using a *nix operating system which operates with debian packages you can download the MQTT CLI debian package from the [releases page](https://github.com/hivemq/mqtt-cli/releases) via `wget` or `curl`
If you are using a *nix operating system which operates with debian packages you can download the MQTT CLI debian
package from the [releases page](https://github.com/hivemq/mqtt-cli/releases) via `wget` or `curl`
and install the package with `sudo dpkg -i` or `sudo apt install`:

```
Expand All @@ -68,13 +81,16 @@ sudo apt install ./mqtt-cli-4.15.0.deb

## RPM Package

For Red Hat, Fedora, Mandriva, OpenSuse, CentOS distributions you can use the rpm package provided at [releases page](https://github.com/hivemq/mqtt-cli/releases).
For Red Hat, Fedora, Mandriva, OpenSuse, CentOS distributions you can use the rpm package provided
at [releases page](https://github.com/hivemq/mqtt-cli/releases).
The preferred way is to install the package via the `yum` package manager. To install the package simply execute:

```
sudo yum install -y https://github.com/hivemq/mqtt-cli/releases/download/v4.15.0/mqtt-cli-4.15.0.rpm
```

***

## Building from source

- mqtt-cli uses [Gradle](https://gradle.org/) to build.
Expand Down Expand Up @@ -105,5 +121,3 @@ For the Windows installer:

For building a local docker image:
`$ ./gradlew jibDockerBuild`


15 changes: 10 additions & 5 deletions docs/_docs/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,20 @@ redirect_from: /docs/logging.html
---

# Logging

***

* All non-shell commands offer an `-l` option by which logging to a logfile under `~/.mqtt-cli/logs` can be activated
* The logfile and log level can be configured in the [MQTT-CLI configuration](configuration.md)
* By specifying the `-l` option for the `shell` command the whole shell-session will be logged to a logfile shown at
start

***
* All non-shell commands offer an ``-l`` option by which logging to a logfile under ``~/.mqtt-cli/logs`` can be activated
* The logfile and loglevel can be configured in the [MQTT-CLI configuration](configuration.md)
* By specifying the ``-l`` option for the ``shell`` command the whole shell-session will be logged to a logfile shown at start

## Direct logging for publish & subscribe
> If you require debug logging for direct access add the `-d` and `-v` options are available for the basic publish and subscribe command

> If you require debug logging for direct access add the `-d` and `-v` options are available for the basic publish and
This conversation was marked as resolved.
Show resolved Hide resolved
> subscribe command

```
$ mqtt pub -i c1 -t test -m "Hello World" -d -h broker.hivemq.com
Expand All @@ -20,5 +26,4 @@ Client '[email protected]' sending CONNECT MqttConnect{keepAlive=60, cleanSta
Client '[email protected]' received CONNACK MqttConnAck{reasonCode=SUCCESS, sessionPresent=false, restrictions=MqttConnAckRestrictions{receiveMaximum=10, maximumPacketSize=268435460, topicAliasMaximum=5, maximumQos=EXACTLY_ONCE, retainAvailable=true, wildcardSubscriptionAvailable=true, sharedSubscriptionAvailable=true, subscriptionIdentifiersAvailable=true}}
Client '[email protected]' sending PUBLISH ('Hello World') MqttPublish{topic=test, payload=11byte, qos=AT_MOST_ONCE, retain=false}
Client '[email protected]' received PUBLISH acknowledgement MqttPublishResult{publish=MqttPublish{topic=test, payload=11byte, qos=AT_MOST_ONCE, retain=false}}

```
Loading