diff --git a/docs/developer-config.md b/docs/developer-config.md new file mode 100644 index 0000000..54c8b22 --- /dev/null +++ b/docs/developer-config.md @@ -0,0 +1,55 @@ +# Default developer configuration + +If you build this image with MQ Advanced for Developers, then an optional set of configuration can be applied automatically. This configures your Queue Manager with a set of default objects that you can use to quickly get started developing with IBM MQ. If you do not want the default objects to be created you can set the `MQ_DEV` environment variable to `false`. + +## Environment variables + +The MQ Developer Defaults supports some customization options, these are all controlled using environment variables: + +* **MQ_DEV** - Set this to `false` to stop the default objects being created. +* **MQ_ADMIN_PASSWORD** - Changes the password of the `admin` user. Must be at least 8 characters long. +* **MQ_APP_PASSWORD** - Changes the password of the app user. If set, this will cause the `DEV.APP.SVRCONN` channel to become secured and only allow connections that supply a valid userid and password. Must be at least 8 characters long. +* **MQ_TLS_KEYSTORE** - Allows you to supply the location of a PKCS#12 keystore containing a single certificate which you want to use in both the web console and the queue manager. Requires `MQ_TLS_PASSPHRASE`. When enabled the channels created will be secured using the `TLS_RSA_WITH_AES_128_CBC_SHA256` CipherSpec. *Note*: you will need to make the keystore available inside your container, this can be done by mounting a volume to your container. +* **MQ_TLS_PASSPHRASE** - Passphrase for the keystore referenced in `MQ_TLS_KEYSTORE`. + +## Details of the default configuration + +The following users are created: + +* User **admin** for administration (in the `mqm` group). Default password is **passw0rd**. +* User **app** for messaging (in a group called `mqclient`). No password by default. + +Users in `mqclient` group have been given access connect to all queues and topics starting with `DEV.**` and have `put`, `get`, `pub`, `sub`, `browse` and `inq` permissions. + +The following queues and topics are created: + +* DEV.QUEUE.1 +* DEV.QUEUE.2 +* DEV.QUEUE.3 +* DEV.DEAD.LETTER.QUEUE - configured as the Queue Manager's Dead Letter Queue. +* DEV.BASE.TOPIC - uses a topic string of `dev/`. + +Two channels are created, one for administration, the other for normal messaging: + +* DEV.ADMIN.SVRCONN - configured to only allow the `admin` user to connect into it. A user and password must be supplied. +* DEV.APP.SVRCONN - does not allow administrative users to connect. Password is optional unless you choose a password for app users. + +A new listener is created (the SYSTEM listener is fine, but system objects are not shown by default in the web console): + +* DEV.LISTENER.TCP - listens on port 1414. + + +## Web Console + +By default the MQ Advanced for Developers image will start the IBM MQ Web Console that allows you to administer your Queue Manager running on your container. When the web console has been started, you can access it by opening a web browser and navigating to https://:9443/ibmmq/console. Where is replaced by the IP address of your running container. + +When you navigate to this page you may be presented with a security exception warning. This happens because, by default, the web console creates a self-signed certificate to use for the HTTPS operations. This certificate is not trusted by your browser and has an incorrect distinguished name. + +If you choose to accept the security warning, you will be presented with the login menu for the IBM MQ Web Console. The default login for the console is: + +* **User:** admin +* **Password:** passw0rd + +If you wish to change the password for the admin user, this can be done using the `MQ_ADMIN_PASSWORD` environment variable. If you supply a PKCS#12 keystore using the `MQ_TLS_KEYSTORE` environment variable, then the web console will be configured to use the certificate inside the keystore for HTTPS operations. + +If you do not wish the web console to run, you can disable it by setting the environment variable `MQ_DISABLE_WEB_CONSOLE` to `true`. diff --git a/docs/internals.md b/docs/internals.md index 07ea940..a39fb26 100644 --- a/docs/internals.md +++ b/docs/internals.md @@ -8,6 +8,7 @@ The resulting Docker image contains the following: * MQ installation (under `/opt/mqm`) * Three additional programs, to enable running in a containerized environment: - `runmqserver` - The main process, which creates and runs a queue manager + - `runmqdevserver` - The main process for MQ Advanced for Developers - `chkmqhealthy` - Checks the health of the queue manager. This can be used by (say) a Kubernetes liveness probe. - `chkmqready` - Checks if the queue manager is ready for work. This can be used by (say) a Kubernetes readiness probe. @@ -23,3 +24,15 @@ The `runmqserver` command has the following responsibilities: - Works as PID 1, so is responsible for [reaping zombie processes](https://blog.phusion.nl/2015/01/20/docker-and-the-pid-1-zombie-reaping-problem/) * Creating and starting a queue manager * Configuring the queue manager, by running any MQSC scripts found under `/etc/mqm` +* Indicates to the `chkmqready` command that configuration is complete, and that normal readiness checking can happen. This is done by writing a file into `/run/runmqserver` + +In addition, for MQ Advanced for Developers only, the web server is started. + +## runmqdevserver +The `runmqdevserver` command is added to the MQ Advanced for Developers image only. It does the following, before invoking `runmqserver`: + +1. Sets passwords based on supplied environment variables +2. Generates MQSC files to put in `/etc/mqm`, based on a template, which is updated with values based on supplied environment variables. +3. If requested, it creates TLS key stores under `/run/runmqdevserver`, and configures MQ and the web server to use them + +A special version of `runmqserver` is used in the developer image, which performs extra actions like starting the web server. This is built using the `mqdev` [build constraint](https://golang.org/pkg/go/build/#hdr-Build_Constraints). \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..3420eb8 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,17 @@ +# Troubleshooting + +## AMQ7017: Log not available +If you see this message in the container logs, it means that the directory being used for the container's volume doesn't use a filesystem supported by IBM MQ. To solve this, you need to make sure the container's `/mnt/mqm` volume is put on a supported filesystem. The best way to do this is to use [Docker volumes](https://docs.docker.com/storage/volumes/), instead of bind-mounted directories. + +## Container command not found or does not exist +This message also appears as "System error: no such file or directory" in some versions of Docker. This can happen using a Docker client on Windows, and is related to line-ending characters. When you clone the Git repository on Windows, Git is often configured to convert any UNIX-style LF line-endings to Windows-style CRLF line-endings. Files with these line-endings end up in the built Docker image, and cause the container to fail at start-up. One solution to this problem is to stop Git from converting the line-ending characters, with the following command: + +``` +git config --global core.autocrlf input +``` + +## Old Linux kernel versions +MQ works best if you have a Linux kernel version of V3.16 or higher (run `uname -r` to check). + +If you have an older version, you might need to add the [`--ipc host`](https://docs.docker.com/engine/reference/run/#ipc-settings-ipc) option when you run an MQ container. The reason for this is that IBM MQ uses shared memory, and on Linux kernels prior to V3.16, containers are usually limited to 32 MB of shared memory. In a [change](https://git.kernel.org/cgit/linux/kernel/git/mhocko/mm.git/commit/include/uapi/linux/shm.h?id=060028bac94bf60a65415d1d55a359c3a17d5c31 +) to Linux kernel V3.16, the hard-coded limit is greatly increased. This kernel version is available in Ubuntu 14.04.2 onwards, Fedora V20 onwards, and boot2docker V1.2 onwards. Some Linux distributions, like Red Hat Enterprise Linux, patch older kernel versions, so you might find that the patch has been applied already, even if you see a lower kernel version number. If you are using a host with an older kernel version, then you can still run MQ, but you have to give it access to the host's IPC namespace using the [`--ipc host`](https://docs.docker.com/engine/reference/run/#ipc-settings-ipc) option on `docker run`. Note that this reduces the security isolation of your container. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..4614338 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,81 @@ +# Usage + +In order to use the image, it is necessary to accept the terms of the IBM MQ license. This is achieved by specifying the environment variable `LICENSE` equal to `accept` when running the image. You can also view the license terms by setting this variable to `view`. Failure to set the variable will result in the termination of the container with a usage statement. You can view the license in a different language by also setting the `LANG` environment variable. + +## Running with the default configuration +You can run a queue manager with the default configuration and a listener on port 1414 using the following command. For example, the following command creates and starts a queue manager called `QM1`, and maps port 1414 on the host to the MQ listener on port 1414 inside the container, as well as port 9443 on the host to the web console on port 9443 inside the container: + +``` +docker run \ + --env LICENSE=accept \ + --env MQ_QMGR_NAME=QM1 \ + --publish 1414:1414 \ + --publish 9443:9443 \ + --detach \ + ibmcom/mq +``` + +## Running with the default configuration and a volume +The above example will not persist any configuration data or messages across container runs. In order to do this, you need to use a [volume](https://docs.docker.com/engine/admin/volumes/volumes/). For example, you can create a volume with the following command: + +``` +docker volume create qm1data +``` + +You can then run a queue manager using this volume as follows: + +``` +docker run \ + --env LICENSE=accept \ + --env MQ_QMGR_NAME=QM1 \ + --publish 1414:1414 \ + --publish 9443:9443 \ + --detach \ + --volume qm1data:/mnt/mqm \ + ibmcom/mq +``` + +The Docker image always uses `/mnt/mqm` for MQ data, which is correctly linked for you under `/var/mqm` at runtime. This is to handle problems with file permissions on some platforms. + +## Customizing the queue manager configuration + +You can customize the configuration in several ways: + +1. For getting started, you can use the [default developer configuration](developer-config.md), which is available out-of-the-box for the MQ Advanced for Developers image +2. By creating your own image and adding your own MQSC file into the `/etc/mqm` directory on the image. This file will be run when your queue manager is created. +3. By using [remote MQ administration](http://www-01.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.adm.doc/q021090_.htm), via an MQ command server, the MQ HTTP APIs, or using a tool such as the MQ web console or MQ Explorer. + +Note that a listener is always created on port 1414 inside the container. This port can be mapped to any port on the Docker host. + +The following is an *example* `Dockerfile` for creating your own pre-configured image, which adds a custom `config.mqsc` and an administrative user `alice`. Note that it is not normally recommended to include passwords in this way: + +```dockerfile +FROM ibmcom/mq +RUN useradd alice -G mqm && \ + echo alice:passw0rd | chpasswd +COPY 20-config.mqsc /etc/mqm/ +``` + +Here is an example corresponding `20-config.mqsc` script from the [mqdev blog](https://www.ibm.com/developerworks/community/blogs/messaging/entry/getting_going_without_turning_off_mq_security?lang=en), which allows users with passwords to connect on the `PASSWORD.SVRCONN` channel: + +``` +DEFINE CHANNEL(PASSWORD.SVRCONN) CHLTYPE(SVRCONN) REPLACE +SET CHLAUTH(PASSWORD.SVRCONN) TYPE(BLOCKUSER) USERLIST('nobody') DESCR('Allow privileged users on this channel') +SET CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(NOACCESS) DESCR('BackStop rule') +SET CHLAUTH(PASSWORD.SVRCONN) TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(CHANNEL) CHCKCLNT(REQUIRED) +ALTER AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS) AUTHTYPE(IDPWOS) ADOPTCTX(YES) +REFRESH SECURITY TYPE(CONNAUTH) +``` + +## Running MQ commands +It is recommended that you configure MQ in your own custom image. However, you may need to run MQ commands directly inside the process space of the container. To run a command against a running queue manager, you can use `docker exec`, for example: + +``` +docker exec \ + --tty \ + --interactive \ + ${CONTAINER_ID} \ + dspmq +``` + +Using this technique, you can have full control over all aspects of the MQ installation. Note that if you use this technique to make changes to the filesystem, then those changes would be lost if you re-created your container unless you make those changes in volumes.