README.md

   1 <!--
   2 SPDX-FileCopyrightText: 2022 Frank Doepper
   3
   4 SPDX-License-Identifier: FSFAP
   5 -->
   6
   7 # haskell-amqp-utils
   8 generic AMQP commandline tools for use with RabbitMQ
   9
  10 - consumer (`konsum`)
  11 - publisher (`agitprop`)
  12 - rpc client and worker (`plane` / `arbeite`)
  13
  14 ## konsum - an AMQP consumer.
  15
  16 **konsum** [*options*]
  17
  18
  19 ### OPTIONS
  20
  21       -r BINDINGKEY  --bindingkey=BINDINGKEY          AMQP binding key
  22       -X[EXE]        --execute[=EXE]                  Callback Script File (implies -t) (-X without arg: /usr/lib/haskell-amqp-utils/callback)
  23       -a ARG         --args=ARG, --arg=ARG            additional argument for -X callback
  24       -t[DIR]        --tempdir[=DIR], --target[=DIR]  tempdir (default: no file creation, -t without arg: /tmp)
  25       -f INT         --prefetch=INT                   Prefetch count. (0=unlimited, 1=off, default: 1)
  26       -A             --ack                            Toggle ack messages (default: True)
  27       -R             --requeuenack                    Toggle requeue when rejected (default: True)
  28                      --stream_offset=OFFSET           x-stream-offset consumer argument
  29       -l INT         --charlimit=INT                  limit number of shown body chars (default: unlimited)
  30       -q QUEUENAME   --queue=QUEUENAME                Ignore Exchange and bind to existing Queue
  31       -i             --simple                         call callback with one arg (filename) only
  32       -j             --cleanup                        Toggle remove tempfile after script call. Default False, but default True if --simple (-i)
  33       -Q TEMPQNAME   --qname=TEMPQNAME                Name for temporary exclusive Queue
  34       -x EXCHANGE    --exchange=EXCHANGE              AMQP Exchange (default: "")
  35       -o SERVER      --server=SERVER                  AMQP Server (default: localhost)
  36       -y VHOST       --vhost=VHOST                    AMQP Virtual Host (default: /)
  37       -p PORT        --port=PORT                      Server Port Number (default: 5672)
  38       -T             --tls                            Toggle TLS (default: False)
  39       -c CERTFILE    --cert=CERTFILE                  TLS Client Certificate File
  40       -k KEYFILE     --key=KEYFILE                    TLS Client Private Key File
  41       -U USERNAME    --user=USERNAME                  Username for Auth
  42       -P PASSWORD    --pass=PASSWORD                  Password for Auth
  43       -s INT         --heartbeats=INT                 heartbeat interval (0=disable, default: set by server)
  44       -n NAME        --name=NAME                      connection name, will be shown in RabbitMQ web interface
  45       -w SECONDS     --connect_timeout=SECONDS        timeout for establishing initial connection (default: 600)
  46
  47 ### EXAMPLES
  48
  49 connect to localhost with default credentials and attach to a new temp
  50 queue on the default exchange:
  51
  52     konsum
  53
  54 Connect to a host with TLS on a custom port, authenticating with SSL
  55 client certificate. On every received message a callback is spawned.
  56 The message will be ACKed when the callback exits successfully. First
  57 500 bytes of the message body are printed to stderr. Header infos are
  58 always printed to stderr:
  59
  60     konsum -o amqp.example.com -p 5673 -T -k amqp-key.pem -c amqp-crt.pem -y vhost -x exchange -X./callback.sh -a -c -a callback.config.sh -f 2 -r binding.key.# -l 500
  61
  62 Authenticate with user and pass. Attach to an existing queue. Generate a file
  63 for every message:
  64
  65     konsum -o amqp.example.com -U user -P pass -q queue -t
  66
  67 Provide a custom CA cert for proving the server's identity via
  68 enviroment:
  69
  70     $ env SYSTEM_CERTIFICATE_PATH=/etc/amqp/cacert.crt konsum -T -y vhost -x exchange -r#
  71
  72 You can have no bindings, or you can bind the queue to one or multiple exchanges + binding keys:
  73
  74     konsum -x x1 -r b1 -r b2 -x x2 -r b3
  75
  76 would bind the queue to exchange x1 with binding keys b1 and b2 and to exchange x2 with binding key b3.
  77
  78 Stop with ^C
  79
  80 ## agitprop - an AMQP publisher
  81
  82 **agitprop** [*options*]
  83
  84
  85 If INPUTFILE is a file, the file is sent as a message and the program exits. If
  86 INPUTFILE is a directory, the directory is watched via inotify ("hotfolder
  87 mode") and every file, which is written and closed or moved in gets sent,
  88 optionally only files which match one or several SUFFIXes. Optionally the file
  89 name is written into a message header named HEADERNAME.  Optionally
  90 Content-Type and Content-Encoding headers are set via magic retrieved from file
  91 contents.
  92
  93 Line-by-line mode sends one message per INPUTFILE line.
  94
  95 In "hotfolder mode" multiple directories can be watched and sent with distinct routingkeys.
  96
  97 ### OPTIONS
  98
  99       -r ROUTINGKEY    --routingkey=ROUTINGKEY            AMQP routing key
 100       -f INPUTFILE     --inputfile=INPUTFILE              Message input file (default: <stdin>)
 101       -l               --linemode                         Toggle line-by-line mode (default: False)
 102       -C               --confirm                          Toggle confirms (default: False)
 103                        --msgid=ID                         Message ID
 104                        --type=TYPE                        Message Type
 105                        --userid=USERID                    Message User-ID
 106                        --appid=APPID                      Message App-ID
 107                        --clusterid=CLUSTERID              Message Cluster-ID
 108                        --contenttype=CONTENTTYPE          Message Content-Type
 109                        --contentencoding=CONTENTENCODING  Message Content-Encoding
 110                        --replyto=REPLYTO                  Message Reply-To
 111                        --prio=PRIO                        Message Priority
 112                        --corrid=CORRID                    Message CorrelationID
 113                        --exp=EXP                          Message Expiration
 114       -h HEADER=VALUE  --header=HEADER=VALUE              Message Headers
 115       -F HEADERNAME    --fnheader=HEADERNAME              Put filename into this header
 116       -S SUFFIX        --suffix=SUFFIX                    Allowed file suffixes in hotfolder mode
 117       -u[DIR]          --remove[=DIR], --move[=DIR]       Remove (or move to DIR) sent file in hotfolder mode
 118       -d               --dirscan                          Toggle initial directory scan in hotfolder mode (default: False)
 119       -m               --magic                            Toggle setting content-type and -encoding from file contents (default: False)
 120       -e               --persistent                       Set persistent delivery
 121       -E               --nonpersistent                    Set nonpersistent delivery
 122       -x EXCHANGE      --exchange=EXCHANGE                AMQP Exchange (default: "")
 123       -o SERVER        --server=SERVER                    AMQP Server (default: localhost)
 124       -y VHOST         --vhost=VHOST                      AMQP Virtual Host (default: /)
 125       -p PORT          --port=PORT                        Server Port Number (default: 5672)
 126       -T               --tls                              Toggle TLS (default: False)
 127       -c CERTFILE      --cert=CERTFILE                    TLS Client Certificate File
 128       -k KEYFILE       --key=KEYFILE                      TLS Client Private Key File
 129       -U USERNAME      --user=USERNAME                    Username for Auth
 130       -P PASSWORD      --pass=PASSWORD                    Password for Auth
 131       -s INT           --heartbeats=INT                   heartbeat interval (0=disable, default: set by server)
 132       -n NAME          --name=NAME                        connection name, will be shown in RabbitMQ web interface
 133       -w SECONDS       --connect_timeout=SECONDS          timeout for establishing initial connection (default: 600)
 134
 135 ### EXAMPLES
 136
 137 Send a message containing a file and put the filename into a fileName
 138 message header:
 139
 140     agitprop -x amq.topic -r test -F fileName -f agitprop.hs
 141
 142 Watch two directories dir1 and dir2 and send files from dir1 with routingkey r1
 143 and files from dir2 with routingkey r2, ignoring everything which is not *.txt
 144 or *.zip, and set Content-Type and Content-Encoding automatically, and move all
 145 sent files to subdir "done" (dir1/done and dir2/done, respectively):
 146
 147     agitprop -x amq.topic -F fileName -m -S .txt -S .zip -d -udone -r r1 -f dir1 -r r2 -f dir2
 148
 149 ## plane - an AMQP RPC client.
 150
 151 **plane** [*options*]
 152
 153
 154 ### OPTIONS
 155       -r ROUTINGKEY, -Q ROUTINGKEY  --routingkey=ROUTINGKEY, --qname=ROUTINGKEY  AMQP routing key
 156       -f INPUTFILE                  --inputfile=INPUTFILE                        Message input file (default: <stdin>)
 157       -O OUTPUTFILE                 --outputfile=OUTPUTFILE                      Message output file (default: -)
 158       -t SECONDS                    --rpc_timeout=SECONDS                        How long to wait for reply (default: 5.0)
 159                                     --corrid=CORRID                              Message CorrelationID
 160                                     --exp=EXP                                    Message Expiration
 161       -h HEADER=VALUE               --header=HEADER=VALUE                        Message Headers
 162       -l INT                        --charlimit=INT                              limit number of shown body chars (default: unlimited)
 163       -x EXCHANGE                   --exchange=EXCHANGE                          AMQP Exchange (default: "")
 164       -o SERVER                     --server=SERVER                              AMQP Server (default: localhost)
 165       -y VHOST                      --vhost=VHOST                                AMQP Virtual Host (default: /)
 166       -p PORT                       --port=PORT                                  Server Port Number (default: 5672)
 167       -T                            --tls                                        Toggle TLS (default: False)
 168       -c CERTFILE                   --cert=CERTFILE                              TLS Client Certificate File
 169       -k KEYFILE                    --key=KEYFILE                                TLS Client Private Key File
 170       -U USERNAME                   --user=USERNAME                              Username for Auth
 171       -P PASSWORD                   --pass=PASSWORD                              Password for Auth
 172       -s INT                        --heartbeats=INT                             heartbeat interval (0=disable, default: set by server)
 173       -n NAME                       --name=NAME                                  connection name, will be shown in RabbitMQ web interface
 174       -w SECONDS                    --connect_timeout=SECONDS                    timeout for establishing initial connection (default: 600)
 175
 176 ### EXAMPLES
 177
 178 send "ls" to a remote worker and get the result:
 179
 180     echo ls | plane -o amqp.example.com -T -k amqp.pem -c amqp.pem -y myexchange -Q rpctest
 181
 182 ## arbeite - an AMQP RPC worker.
 183
 184 **arbeite** [*options*]
 185
 186
 187 ### OPTIONS
 188       -X[EXE]       --execute[=EXE]                  Callback Script File (implies -t) (-X without arg: /usr/lib/haskell-amqp-utils/callback)
 189       -a ARG        --args=ARG, --arg=ARG            additional argument for -X callback
 190       -t[DIR]       --tempdir[=DIR], --target[=DIR]  tempdir (default: no file creation, -t without arg: /tmp)
 191       -f INT        --prefetch=INT                   Prefetch count. (0=unlimited, 1=off, default: 1)
 192       -A            --ack                            Toggle ack messages (default: True)
 193       -R            --requeuenack                    Toggle requeue when rejected (default: True)
 194       -l INT        --charlimit=INT                  limit number of shown body chars (default: unlimited)
 195       -q QUEUENAME  --queue=QUEUENAME                Ignore Exchange and bind to existing Queue
 196       -i            --simple                         call callback with one arg (filename) only
 197       -j            --cleanup                        Toggle remove tempfile after script call. Default False, but default True if --simple (-i)
 198       -Q TEMPQNAME  --qname=TEMPQNAME                Name for temporary exclusive Queue
 199       -x EXCHANGE   --exchange=EXCHANGE              AMQP Exchange (default: "")
 200       -o SERVER     --server=SERVER                  AMQP Server (default: localhost)
 201       -y VHOST      --vhost=VHOST                    AMQP Virtual Host (default: /)
 202       -p PORT       --port=PORT                      Server Port Number (default: 5672)
 203       -T            --tls                            Toggle TLS (default: False)
 204       -c CERTFILE   --cert=CERTFILE                  TLS Client Certificate File
 205       -k KEYFILE    --key=KEYFILE                    TLS Client Private Key File
 206       -U USERNAME   --user=USERNAME                  Username for Auth
 207       -P PASSWORD   --pass=PASSWORD                  Password for Auth
 208       -s INT        --heartbeats=INT                 heartbeat interval (0=disable, default: set by server)
 209       -n NAME       --name=NAME                      connection name, will be shown in RabbitMQ web interface
 210       -w SECONDS    --connect_timeout=SECONDS        timeout for establishing initial connection (default: 600)
 211
 212 ### EXAMPLES
 213
 214 provide shell access to a remote user. Very insecure! :-)
 215
 216     arbeite -o amqp.example.com -T -k amqp.pem -c amqp.pem -y myexchange -Q rpctest -i -Xsh
 217
 218
 219 ## callbacks
 220
 221 `konsum` and `arbeite` can execute programs (`-Xprogram`) on reception of a message.
 222
 223 ### normal (old) mode
 224
 225 The callback is called with the following arguments:
 226
 227     -f filename
 228     -n messagenumber
 229
 230 Optionally are added:
 231
 232     -r routingkey
 233     -m contenttype
 234     -e encoding
 235     -i messageid
 236     -t timestamp
 237     -p priority
 238     -R redelivered
 239
 240 Message headers are added through several -h options:
 241
 242     -h HEADER=VALUE
 243
 244 Any additional arguments provided by `-a arg` options are appended.
 245
 246 ### simple (new) mode
 247
 248 Wenn called with `-i` (`--simple`), the callback is called with only the filename
 249 as argument. Any additional arguments provided by `-a arg` options are prepended.
 250
 251 ### ENVIRONMENT
 252
 253 The arguments provided in normal (old) mode are also available as environment
 254 variables in both modes in the callback:
 255
 256     AMQP_FILE
 257     AMQP_NUMBER
 258
 259     AMQP_ROUTINGKEY
 260     AMQP_CONTENTTYPE
 261     AMQP_ENCODING
 262     AMQP_MSGID
 263     AMQP_TIMESTAMP
 264     AMQP_PRIORITY
 265     AMQP_REDELIVERED
 266
 267 And the remaining message properties, too:
 268
 269     AMQP_SIZE
 270     AMQP_TYPE
 271     AMQP_USERID
 272     AMQP_APPID
 273     AMQP_CLUSTERID
 274     AMQP_REPLYTO
 275     AMQP_CORRID
 276     AMQP_EXPIRATION
 277     AMQP_DELIVERYMODE
 278
 279 Message headers, if any, are available as
 280
 281     AMQP_HEADER_KEY_0
 282     AMQP_HEADER_VALUE_0
 283     AMQP_HEADER_KEY_1
 284     AMQP_HEADER_VALUE_1
 285
 286 etc.
 287
 288 ## code, bugs, contribution, etc.
 289
 290 - project page: https://sr.ht/~woffs/haskell-amqp-utils/
 291 - mailing list: https://lists.sr.ht/~woffs/public-inbox
 292 - todo list / bug tracker: https://todo.sr.ht/~woffs/haskell-amqp-utils
 293 - Chat: xmpp:[email protected]?join
 294 - source code:
 295   - git://woffs.de/git/fd/haskell-amqp-utils.git
 296   - https://woffs.de/git/fd/haskell-amqp-utils.git
 297   - https://git.sr.ht/~woffs/haskell-amqp-utils
 298 - Repology: https://repology.org/project/haskell:amqp-utils/packages
 299 - Hackage: https://hackage.haskell.org/package/amqp-utils
 300 - Stackage: https://www.stackage.org/package/amqp-utils