doc/konsum.md

   1 <!--
   2 SPDX-FileCopyrightText: 2022 Frank Doepper
   3
   4 SPDX-License-Identifier: FSFAP
   5 -->
   6
   7 ---
   8 title: konsum
   9 section: 1
  10 header: haskell-amqp-utils
  11 footer: haskell-amqp-utils 0.6.5.0
  12 date: 2022-11-11
  13 ---
  14
  15 # NAME
  16 konsum - an AMQP consumer.
  17
  18 # SYNOPSIS
  19 **konsum** [*options*]
  20
  21 # DESCRIPTION
  22
  23 # OPTIONS
  24
  25       -r BINDINGKEY  --bindingkey=BINDINGKEY          AMQP binding key
  26       -X[EXE]        --execute[=EXE]                  Callback Script File (implies -t) (-X without arg: /usr/lib/haskell-amqp-utils/callback)
  27       -a ARG         --args=ARG, --arg=ARG            additional argument for -X callback
  28       -t[DIR]        --tempdir[=DIR], --target[=DIR]  tempdir (default: no file creation, -t without arg: /tmp)
  29       -f INT         --prefetch=INT                   Prefetch count. (0=unlimited, 1=off, default: 1)
  30       -A             --ack                            Toggle ack messages (default: True)
  31       -R             --requeuenack                    Toggle requeue when rejected (default: True)
  32                      --stream_offset=OFFSET           x-stream-offset consumer argument
  33       -l INT         --charlimit=INT                  limit number of shown body chars (default: unlimited)
  34       -q QUEUENAME   --queue=QUEUENAME                Ignore Exchange and bind to existing Queue
  35       -i             --simple                         call callback with one arg (filename) only
  36       -j             --cleanup                        Toggle remove tempfile after script call. Default False, but default True if --simple (-i)
  37       -Q TEMPQNAME   --qname=TEMPQNAME                Name for temporary exclusive Queue
  38       -x EXCHANGE    --exchange=EXCHANGE              AMQP Exchange (default: "")
  39       -o SERVER      --server=SERVER                  AMQP Server (default: localhost)
  40       -y VHOST       --vhost=VHOST                    AMQP Virtual Host (default: /)
  41       -p PORT        --port=PORT                      Server Port Number (default: 5672)
  42       -T             --tls                            Toggle TLS (default: False)
  43       -c CERTFILE    --cert=CERTFILE                  TLS Client Certificate File
  44       -k KEYFILE     --key=KEYFILE                    TLS Client Private Key File
  45       -U USERNAME    --user=USERNAME                  Username for Auth
  46       -P PASSWORD    --pass=PASSWORD                  Password for Auth
  47       -s INT         --heartbeats=INT                 heartbeat interval (0=disable, default: set by server)
  48       -n NAME        --name=NAME                      connection name, will be shown in RabbitMQ web interface
  49       -w SECONDS     --connect_timeout=SECONDS        timeout for establishing initial connection (default: 600)
  50 <!--
  51 SPDX-FileCopyrightText: 2022 Frank Doepper
  52
  53 SPDX-License-Identifier: FSFAP
  54 -->
  55
  56 # EXAMPLES
  57
  58 connect to localhost with default credentials and attach to a new temp
  59 queue on the default exchange:
  60
  61     konsum
  62
  63 Connect to a host with TLS on a custom port, authenticating with SSL
  64 client certificate. On every received message a callback is spawned.
  65 The message will be ACKed when the callback exits successfully. First
  66 500 bytes of the message body are printed to stderr. Header infos are
  67 always printed to stderr:
  68
  69     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
  70
  71 Authenticate with user and pass. Attach to an existing queue. Generate a file
  72 for every message:
  73
  74     konsum -o amqp.example.com -U user -P pass -q queue -t
  75
  76 Provide a custom CA cert for proving the server's identity via
  77 enviroment:
  78
  79     $ env SYSTEM_CERTIFICATE_PATH=/etc/amqp/cacert.crt konsum -T -y vhost -x exchange -r#
  80
  81 You can have no bindings, or you can bind the queue to one or multiple exchanges + binding keys:
  82
  83     konsum -x x1 -r b1 -r b2 -x x2 -r b3
  84
  85 would bind the queue to exchange x1 with binding keys b1 and b2 and to exchange x2 with binding key b3.
  86
  87 Stop with ^C
  88
  89 <!--
  90 SPDX-FileCopyrightText: 2022 Frank Doepper
  91
  92 SPDX-License-Identifier: FSFAP
  93 -->
  94 # FILES
  95
  96 ## callbacks
  97
  98 `konsum` and `arbeite` can execute programs (`-Xprogram`) on reception of a message.
  99
 100 ### normal (old) mode
 101
 102 The callback is called with the following arguments:
 103
 104     -f filename
 105     -n messagenumber
 106
 107 Optionally are added:
 108
 109     -r routingkey
 110     -m contenttype
 111     -e encoding
 112     -i messageid
 113     -t timestamp
 114     -p priority
 115     -R redelivered
 116
 117 Message headers are added through several -h options:
 118
 119     -h HEADER=VALUE
 120
 121 Any additional arguments provided by `-a arg` options are appended.
 122
 123 ### simple (new) mode
 124
 125 Wenn called with `-i` (`--simple`), the callback is called with only the filename
 126 as argument. Any additional arguments provided by `-a arg` options are prepended.
 127
 128 # ENVIRONMENT
 129
 130 The arguments provided in normal (old) mode are also available as environment
 131 variables in both modes in the callback:
 132
 133     AMQP_FILE
 134     AMQP_NUMBER
 135
 136     AMQP_ROUTINGKEY
 137     AMQP_CONTENTTYPE
 138     AMQP_ENCODING
 139     AMQP_MSGID
 140     AMQP_TIMESTAMP
 141     AMQP_PRIORITY
 142     AMQP_REDELIVERED
 143
 144 And the remaining message properties, too:
 145
 146     AMQP_SIZE
 147     AMQP_TYPE
 148     AMQP_USERID
 149     AMQP_APPID
 150     AMQP_CLUSTERID
 151     AMQP_REPLYTO
 152     AMQP_CORRID
 153     AMQP_EXPIRATION
 154     AMQP_DELIVERYMODE
 155
 156 Message headers, if any, are available as
 157
 158     AMQP_HEADER_KEY_0
 159     AMQP_HEADER_VALUE_0
 160     AMQP_HEADER_KEY_1
 161     AMQP_HEADER_VALUE_1
 162
 163 etc.
 164