v1.1.0

.github/workflows/release-containers.yaml

@@ -0,0 +1,52 @@
+name: Release Containers
+
+on:
+  workflow_dispatch:
+  release:
+    types: [released]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64/v8
+          file: Dockerfile
+          push: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: |
+              simonkowallik/tmconfjs:latest
+              ghcr.io/simonkowallik/tmconfjs:latest
+
+      - name: Docker Hub Description
+        uses: peter-evans/dockerhub-description@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          # docker... https://github.com/peter-evans/dockerhub-description/issues/10
+          password: ${{ secrets.DOCKERHUB_TOKEN }}

Dockerfile

@@ -0,0 +1,9 @@
+FROM node:lts-alpine
+
+WORKDIR /tmconfjs
+
+ADD . /tmconfjs
+
+RUN npm install --global /tmconfjs/
+
+CMD ["tmconfjs"]

README.md

@@ -1,17 +1,23 @@
 # tmconfjs
 
-**tmconfjs** provides a simple parser (`tmconfparse` command) to serialize a tmconf file (eg. `/config/bigip.conf`) to JSON. The produced JSON is printed to `STDOUT`.
+**tmconfjs** provides a simple parser (`tmconfjs` command) to serialize a tmconf file (eg. `/config/bigip.conf`) to JSON. The produced JSON is printed to `STDOUT` or a specified file.
 
-This project is (supposed to be) a minimal wrapper and vendors the necessary code from the community project [F5 BIG-IP Automation Config Converter (BIG-IP ACC)](https://github.com/f5devcentral/f5-automation-config-converter/).
+This project is a minimal wrapper and vendors the necessary code from the community project [F5 BIG-IP Automation Config Converter (BIG-IP ACC)](https://github.com/f5devcentral/f5-automation-config-converter/).
 
-## Usage example
+## Documentation by example
+
+### Installation
 
 ```shell
-npm install -g https://github.com/simonkowallik/tmconfjs
+npm install --global simonkowallik/tmconfjs
 ```
 
+### Command line usage
+
+When installed globally, `tmconfjs` can be invoked as a command:
+
 ```shell
-tmconfparse example/test.tmconf 2>/dev/null \
+tmconfjs example/test.tmconf 2>/dev/null \
     | jq '."ltm profile client-ssl clientssl-secure"'
 ```
 
@@ -39,20 +45,160 @@ tmconfparse example/test.tmconf 2>/dev/null \
 }
 ```
 
-Any errors or info is written to `STDERR`.
+When this repo has been copied or cloned, invoke tmconfjs.js using node. An alternative is using npx, `npx tmconfjs` would work also.
+Errors, warnings or any debug information is written to `STDERR`:
+
+```shell
+node ./tmconfjs.js example/test.tmconf \
+    >/dev/null 2> example/test.tmconf.log
+
+cat example/test.tmconf.log
+```
+
+```shell
+2024-02-23T21:47:31.594Z WARN UNRECOGNIZED LINE: '     auto-check enabled'
+2024-02-23T21:47:31.595Z WARN UNRECOGNIZED LINE: '     auto-phonehome enabled'
+2024-02-23T21:47:31.602Z WARN UNRECOGNIZED LINE: '	time 500'
+2024-02-23T21:47:31.602Z WARN UNRECOGNIZED LINE: '	enabled yes'
+```
+
+Input is also accepted from `STDIN`:
+
+```shell
+cat example/imap.tmconf | node tmconfjs.js
+```
+
+```json
+{
+    "ltm profile imap imap": {
+        "activation-mode": "require"
+    }
+}
+```
+
+The `<file_path>` argument is preferred over `STDIN` however:
+
+```shell
+cat example/imap.tmconf | node tmconfjs.js example/pop3.tmconf
+```
+
+```json
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}
+```
+
+The output can be written to a specified file using `--output` or `-o` when `STDOUT` is not desired:
+
+```shell
+node tmconfjs.js --output example/pop3.json example/pop3.tmconf
+cat example/pop3.json
+```
+
+```json
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}
+```
+
+More debug information is available and might help understand issues:
+
+```shell
+export LOG_LEVEL=debug
+cat example/imap.tmconf | node tmconfjs.js example/pop3.tmconf 2> debug.log
+```
+
+```json
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}
+```
+
+```shell
+cat debug.log
+```
 
 ```shell
-# run node and tmconfparse.js as first argument followed by tmconfparse arguments.
-node ./tmconfparse.js example/test.tmconf >/dev/null
+2024-02-23T21:54:04.300Z DEBUG Parsing from <file_path>: example/pop3.tmconf
+2024-02-23T21:54:04.302Z DEBUG Parsing data
 ```
 
+### Container / Docker
+
+Note the docker run options, `--rm` deletes the container right after it was executed and ended,
+`-i` run the container interactively (required for STDIN to work). Also note the absence of the common `-t` option, which indicates a TTY/terminal - STDIN would fail when this is used.
+
 ```shell
-2024-02-17 00:29:17 WARN UNRECOGNIZED LINE: '     auto-check enabled'
-2024-02-17 00:29:17 WARN UNRECOGNIZED LINE: '     auto-phonehome enabled'
-2024-02-17 00:29:17 WARN UNRECOGNIZED LINE: '   time 500'
-2024-02-17 00:29:17 WARN UNRECOGNIZED LINE: '   enabled yes'
+cat example/imap.tmconf | docker run --rm -i simonkowallik/tmconfjs
+```
+
+```json
+{
+    "ltm profile imap imap": {
+        "activation-mode": "require"
+    }
+}
+```
+
+Using volumes is another option:
+
+```shell
+docker run --rm -v $PWD/example:/data simonkowallik/tmconfjs \
+    tmconfjs /data/pop3.tmconf -o /data/pop3.json
+
+cat example/pop3.json
+```
+
+```json
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}
+```
+
+### Use as module
+
+A simple `demo.js` is available at [example/demo.js](./example/demo.js).
+
+Just require either `parse` or `parseFile`. Both take a string as input, `parse` expects tmconf within the string while `parseFile` expects a path to a tmconf file.
+
+```javascript
+// demo.js
+'use strict'
+
+// use parse function from tmconfjs.js
+const parse = require('../tmconfjs.js').parse
+
+const tmconf = `
+ltm profile pop3 pop3 {
+    activation-mode require
+}`
+
+// supply string with tmconf to parse function
+const tmconfAsJSON = parse(tmconf)
+
+console.log(JSON.stringify(tmconfAsJSON, null, 4))
+```
+
+```shell
+node example/demo.js
+```
+
+```json
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}
 ```
 
 ## Disclaimer
 
-Please read and understand the LICENSE as well as the provided SUPPORT.md.
+Please read and understand the [LICENSE](./LICENSE) as well as the provided [SUPPORT.md](./SUPPORT.md).

SUPPORT.md

@@ -2,4 +2,6 @@
 
 There is no support on this project. It is maintained on best effort basis without any warranties. Please read and understand the LICENSE first.
 
-Any software or components used in this project have their own LICENSE and SUPPORT policies.
+For any software or components used in this project, read their own LICENSE and SUPPORT policies.
+
+If you decide to use this project, you are solely responsible.

example/demo.js

@@ -0,0 +1,15 @@
+// demo.js
+'use strict'
+
+// use parse function from tmconfjs.js
+const parse = require('../tmconfjs.js').parse
+
+const tmconf = `
+ltm profile pop3 pop3 {
+    activation-mode require
+}`
+
+// supply string with tmconf to parse function
+const tmconfAsJSON = parse(tmconf)
+
+console.log(JSON.stringify(tmconfAsJSON, null, 4))

example/imap.tmconf

@@ -0,0 +1,3 @@
+ltm profile imap imap {
+    activation-mode require
+}

example/pop3.json

@@ -0,0 +1,5 @@
+{
+    "ltm profile pop3 pop3": {
+        "activation-mode": "require"
+    }
+}

example/pop3.tmconf

@@ -0,0 +1,3 @@
+ltm profile pop3 pop3 {
+    activation-mode require
+}

example/test.tmconf.json

@@ -2666,4 +2666,4 @@
         },
         "route-domain": "/Common/0"
     }
-}
+}