README.md

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