Getting Started

• 1: Security
• 2: Authentication with Sense
• 3: Colors & formatting
• 4: Dry runs

1 - Security

• Virus scanning
  • Positive scan vs false positives
• Signed binaries

Ctrl-Q is open source and you have access to all source code.

It is your responsibility to determine if Ctrl-Q is suitable for your use case.
The creators of Ctrl-Q, including Ptarmigan Labs, Göran Sander or any other contributor, can and must never be held liable to past or future security issues of Ctrl-Q. If you have security concerns or ideas around Ctrl-Q, please get involved in the project and contribute to making it better!

If you discover a serious bug with Ctrl-Q that may pose a security problem, please disclose it
confidentially to security@ptarmiganlabs.com first, so it can be assessed and hopefully fixed
prior to being exploited.

Please do not raise GitHub issues for serious security-related doubts or problems.

Virus scanning

Every time a Ctrl-Q release is done the created binaries are sent to VirusTotal for scanning.
VirusTotal acts as an aggregated virus scanner that sends the Ctrl-Q binaries to dozens of anti-virus scanners, including many of the major/most widely used ones.

Links to the VirusTotal scan report are included in each release notes, making it easy to check the status of each binary:

A VirusTotal scan that reports “no risks found” can look like this:

Positive scan vs false positives

If one or more of the security vendors used by VirusTotal reports an issue you have to make a decision.
Is it a real issue or a false positive?

You have to decide this yourself, but some general lines of thought can be:

Is it a single vendor that reports the Ctrl-Q binary file to be a risk, or several vendors?
If one vendor reports an issue and 60+ vendors don't, you might be looking at a false positive.

But again - at the end of the day it’s you that must make that decision.

A scan where a single security vendor reports an issue can look like this:

Signed binaries

The macOS executable binary is signed and notarized by Apple’s standard process.
A warning may still be shown first time the app is started. This is expected and normal.

The Windows executable binary is signed by “Ptarmigan Labs AB”.

2 - Authentication with Sense

Certificates

If the --auth-type option is set to cert, Ctrl-Q will authenticate with Qlik Sense Enterprise using certificates.
This is the default authentication method that will be used if no --auth-type option is specified.

These certificates are exported from the QMC and stored on disk in PEM format.

Three certificate files are needed (and exported from the QMC):

1. The client certificate, which is used to authenticate with the Sense engine.
2. The client key, which is used to authenticate with the Sense engine.
3. The root certificate, which is needed to verify the Sense server’s certificate (as Qlik Sense uses a self-signed certificate).

Ctrl-Q can reference these certificates in two ways:

1. if one or more of the --auth-cert-file, auth-cert-key-file and --auth-root-cert-file options are used, Ctrl-Q will read the certificates from the disk file(s) pointed to by those options.
2. If one or more of the options above are not specified when Ctrl-Q is started, it will look for certificates in the config folder in the same folder as the Ctrl-Q executable.
   1. The certificate files must then be named client.pem, client_key.pem and root.pem, i.e. the names used by the QMC when exporting the certificates.

If the -secure false option is used, Ctrl-Q will not verify the Sense server’s certificate.
This is not recommended from a security perspective, but can still be useful if you are having trouble getting Ctrl-Q to authenticate with Sense.

The options --auth-user-dir and -auth-user-id are also needed to authenticate with Sense.
They define which user will be used when interacting with both the engine and repository APIs.

Strict or relaxed certificate validation

When using certificate authentication, Ctrl-Q will by default validate the Sense server’s certificate.
This happens as the default value for the --secure option is true.

What does “validate the certificate” mean?

Validating a certificate means that Ctrl-Q will check that the certificate is signed by a trusted authority, that it has not expired, and that the server’s hostname matches the certificate’s common name.

For example, if the certificate is created for a host called pro2-win1.lab.ptarmiganlabs.net, Ctrl-Q will - by verifying the server certificate - check that the server it is connecting to is indeed pro2-win1.lab.ptarmiganlabs.net.
If the server’s hostname does not match the certificate’s common name, Ctrl-Q will refuse to connect.
Looks like this:

PS C:\tools\ctrl-q> .\ctrl-q.exe connection-test `
>> --host pro2-win1.ptarmiganlabs.net `
>> --auth-user-dir LAB `
>> --auth-user-id goran
2024-03-09T13:42:31.263Z info: -----------------------------------------------------------
2024-03-09T13:42:31.263Z info: | Ctrl-Q
2024-03-09T13:42:31.263Z info: |
2024-03-09T13:42:31.263Z info: | Version      : 3.15.2
2024-03-09T13:42:31.263Z info: | Log level    : info
2024-03-09T13:42:31.263Z info: |
2024-03-09T13:42:31.263Z info: | Command      : connection-test
2024-03-09T13:42:31.263Z info: |              : test connection to Qlik Sense server.
2024-03-09T13:42:31.263Z info: |
2024-03-09T13:42:31.263Z info: | Run Ctrl-Q with the '--help' option to see a list of all available options for this command.
2024-03-09T13:42:31.263Z info: |
2024-03-09T13:42:31.263Z info: | https://github.com/ptarmiganlabs/ctrl-q
2024-03-09T13:42:31.263Z info: ----------------------------------------------------------
2024-03-09T13:42:31.263Z info:
2024-03-09T13:42:31.278Z info: Testing connection to Qlik Sense server pro2-win1.ptarmiganlabs.net on port 4242
2024-03-09T13:42:31.403Z error: GET ABOUT INFO: Hostname/IP does not match certificate's altnames: Host: pro2-win1.ptarmiganlabs.net. is not in the cert's altnames: DNS:pro2-win1.lab.ptarmiganlabs.net

Ctrl-Q tells us that something is not right with the certificate and we even get a pretty clear message about what is wrong.

Changing the command to use the correct hostname makes the error go away and the command works as expected:

PS C:\tools\ctrl-q> .\ctrl-q.exe connection-test `
>> --host pro2-win1.lab.ptarmiganlabs.net `
>> --auth-user-dir LAB `
>> --auth-user-id goran
2024-03-09T13:50:10.741Z info: -----------------------------------------------------------
2024-03-09T13:50:10.741Z info: | Ctrl-Q
2024-03-09T13:50:10.741Z info: |
2024-03-09T13:50:10.741Z info: | Version      : 3.15.2
2024-03-09T13:50:10.741Z info: | Log level    : info
2024-03-09T13:50:10.741Z info: |
2024-03-09T13:50:10.741Z info: | Command      : connection-test
2024-03-09T13:50:10.741Z info: |              : test connection to Qlik Sense server.
2024-03-09T13:50:10.741Z info: |
2024-03-09T13:50:10.741Z info: | Run Ctrl-Q with the '--help' option to see a list of all available options for this command.
2024-03-09T13:50:10.741Z info: |
2024-03-09T13:50:10.757Z info: | https://github.com/ptarmiganlabs/ctrl-q
2024-03-09T13:50:10.757Z info: ----------------------------------------------------------
2024-03-09T13:50:10.757Z info:
2024-03-09T13:50:10.757Z info: Testing connection to Qlik Sense server pro2-win1.lab.ptarmiganlabs.net on port 4242
2024-03-09T13:50:10.913Z info: Successfully connected to Qlik Sense server pro2-win1.lab.ptarmiganlabs.net on port 4242
2024-03-09T13:50:10.913Z info: Qlik Sense repository build version: 31.36.2.0
2024-03-09T13:50:10.913Z info: Qlik Sense repository build date: 1/11/2024 22:04:12 PM

All this said, if you are having trouble getting Ctrl-Q to connect to Sense, you can use the --secure false option to disable certificate validation. Not preferred from a security perspective, but it can still be useful if you are having trouble getting Ctrl-Q to authenticate with Sense.

Ports used for certificate authentication

When using certificate authentication, Ctrl-Q will connect to the Qlik Engine API on port 4747.

When using certificate authentication, Ctrl-Q will connect directly to the various Qlik Sense services on the port exposed by each service:

• Qlik Repository Service (QRS) on port 4242
• Qlik Proxy Service (QPS) on port 4243
• Qlik Engine Service (QES) on port 4747

If the default ports are not used, each Ctrl-Q command allows you to specify the port to use for each Sense service.

JWTs

If the --auth-type option is set to jwt, Ctrl-Q will authenticate with Qlik Sense Enterprise using JWTs.

JWTs - JSON Web Tokens - are a standard way of authenticating with web services, where a token is issued by an authentication service and then used to authenticate with other services.
JWTs contain a number of claims, including the user ID, which is used to identify the user.

When Ctrl-Q is started with --auth-type option set to jwt, it will then look for an option called --auth-jwt.
Pass in the JWT as the value of this option, and Ctrl-Q will use it to authenticate with Sense.
Embed the JWT in double quotes if it contains special characters (e.g. spaces).

Ports used for JWT authentication

Given the nature of JWT authentication and the fact that it is handled on a virtual proxy level, Ctrl-Q cannot connect directly to the Qlik Sense services when using JWT authentication.
Instead all access must go via a virtual proxy that is configured to use JWT authentication.

This in turn means that Ctrl-Q will need to use whatever port the virtual proxy is configured to use.
Usually this is port 443, but it can be any port, as configured in the proxy linked to the virtual proxy.

Remember to specify the correct port when using JWT authentication, using the --port (might be called --proxy-port or similar in some Ctrl-Q commands) option.

3 - Colors & formatting

• All OSs: plain text
• Windows 10 using Windows Terminal
• macOS and Linux

Some of the Ctrl-Q commands use colors and emojis to better communicate the information retrieved from Qlik Sense.
The task tree view is an example, but more commands may use colors in the future.

The use of colors in console/command line applications has been around since at least the 80s.
MS-DOS supported it, as did early Windows versions.

Today this feature is quite fragmented.

Console applications using colors are natively supported on macOS and Linux.
On Windows Server 2016 and earlier it’s very hard to get this working, later versions may be easier.
On Windows 10 and later it’s possible to use Microsoft’s excellent new command line shell, Windows Terminal.
Highly recommended if you use a desktop Windows operating system!

Ctrl-Q tries to offer plain text visuals unless extra features, flare and color is enabled via command line parameters.

Some examples follow, showing different views of reload task trees.

All OSs: plain text

The command for the most basic task tree is

.\ctrl-q.exe task-get `
--auth-type cert `
--host pro2-win1.lab.ptarmiganlabs.net `
--auth-user-dir LAB `
--auth-user-id goran `
--output-format tree `
--output-dest screen

Add the --tree-details option and the result contains a lot more details for each task. Not very easy to read though.
Note: the task-get command has lots of options, these are described in more detail on this page.

.\ctrl-q.exe task-get `
--auth-type cert `
--host pro2-win1.lab.ptarmiganlabs.net `
--auth-user-dir LAB `
--auth-user-id goran `
--output-format tree `
--output-dest screen `
--tree-details

Windows 10 using Windows Terminal

Thanks to Windows Terminal handling text coloring and emojis we can add a couple of options:

• --tree-icons to get emojis showing the result from each task’s last execution (success, fail etc)
• --text-color yes to get nicely colored text in the task tree

.\ctrl-q.exe task-get `
--auth-type cert `
--host pro2-win1.lab.ptarmiganlabs.net `
--auth-user-dir LAB `
--auth-user-id goran `
--output-format tree `
--output-dest screen `
--tree-icons `
--text-color yes

Adding --tree-details gives us a tree that’s a lot easier to read compared to previous, uncolored version.

.\ctrl-q.exe task-get `
--auth-type cert `
--host pro2-win1.lab.ptarmiganlabs.net `
--auth-user-dir LAB `
--auth-user-id goran `
--output-format tree `
--output-dest screen `
--tree-icons `
--text-color yes `
--tree-details

macOS and Linux

A task tree with colors on macOS and Linux versions of Ctrl-Q looks exactly like same as in Windows Terminal.
The only difference is that you don’t have to install a new command line shell.

4 - Dry runs

Many of Ctrl-Q’s commands will create, update or delete things in Sense.

As long as you have specified the correct parameters that’s all good - but there is also the risk of using incorrect parameters or filters, causing too many (or too few or the wrong) resources in Sense to be affected.

Most Ctrl-Q commands that change things in Sense have a --dry-run option.
If used, Ctrl-Q will not make any changes in Sense, but instead only show what would happen.

It’s thus a very good idea to first do a dry run of the intended command, verify that the correct things would happen and then finally do a real execution of the desired Ctrl-Q command.

Might take a bit of extra time, but better safe than sorry.