Documentation/Queue Protocol

Contents 1 Queue Protocol 2 Session Commands 2.1 AUTH 2.2 PASS SYS 2.3 PASS USER 2.4 QUIT 2.5 QWAIT 2.6 QFLUSH 3 Addressing Commands 3.1 ADDRESS RESOLVE 3.2 DOMAIN LOCATION 4 Queue "Callback" Commands 4.1 QABRT 4.2 QADDM 4.3 QADDQ 4.4 QBODY 4.5 QBRAW 4.6 QCOPY 4.7 QCREA 4.8 QDELE 4.9 QDONE 4.10 QDSPC 4.11 QGREP 4.12 QHEAD 4.13 QINFO 4.14 QMIME 4.15 QMOD FROM 4.16 QMOD FLAGS 4.17 QMOD LOCAL 4.18 QMOD MAILBOX 4.19 QMOD RAW 4.20 QMOD TO 4.21 QMOVE 4.22 QRCP 4.23 QRETR 4.24 QRTS 4.25 QRUN 5 Queue "Search" Commands 5.1 QSRCH DOMAIN 5.2 QSRCH HEADER 5.3 QSRCH BODY 5.4 QSRCH BRAW 6 Queue "Store" Commands 6.1 QSTOR ADDRESS 6.2 QSTOR CAL 6.3 QSTOR FLAGS 6.4 QSTOR FROM 6.5 QSTOR LOCAL 6.6 QSTOR MESSAGE 6.7 QSTOR RAW 6.8 QSTOR TO

[edit] Queue Protocol

The Bongo Queue is a set of mail spools, numbered, through which mail passes before it finally arrives at the Bongo Store.

It is run by the Queue Agent, and other agents may register with this agent in order to see mail as it passes through.

[edit] Session Commands

[edit] AUTH

Description: Verifies the system password and enables manager level access for the client.

Syntax: AUTH <md5 hash of system password>

Response: none

Results:

1. 1000 OK
2. 3242 Bad Authentication

Example:

   AUTH 0376AF4B57CE88147693730583947830
   1000 OK

[edit] PASS SYS

Description: Verifies the system password and enables manager level access for the client.

Restrictions: none

Syntax: PASS SYS <password>

[edit] PASS USER

Description: Verifies the user's password, adds the IDENTITY flag to the client session, and binds the userid to the session.

Restrictions:

Syntax: PASS USER <username> <password>

Response: none

Results:

1. 1000 OK
2. 3010 Invalid Arguments
3. 3242 Bad Authentication

Example:

   PASS USER john bongo
   1000 OK

[edit] QUIT

Description: Causes the server to close the current connection and clean up resources associated with it.

Restrictions: none

Syntax: QUIT

Response: none

Results:

1. 1000 OK

Example:

   QUIT
   1000 OK Signing Off

[edit] QWAIT

Description: Register to listen for mail on a given mail queue. This puts the queue agent into a "callback" mode, where it will initiate connections to the registered agent to deal with mail waiting for it in the queue.

Syntax: QWAIT <queue> <port> <identifier>

Results:

1. 1000 OK Queue Watch mode
2. 3010 Bad arguments

[edit] QFLUSH

Description: Asks the queue agent to flush the queues - useful for trying to move mail which previously failed to move due to transient errors.

Syntax: QFLUSH

Results:

1. 1000 OK

[edit] Addressing Commands

[edit] ADDRESS RESOLVE

Description: Determines whether or not an address is a local address, and what address (if any) it really resolves to

Syntax: ADDRESS RESOLVE <address>

Results:

1. 1000 LOCAL <username>
2. 1001 RELAY <address>
3. 1002 REMOTE <address>
4. 4000 Internal error / loop
5. 4001 No such user

[edit] DOMAIN LOCATION

Description: Determines whether or not a queue accepts mail for a given domain

Syntax: DOMAIN LOCATION <address>

Results:

1. 1000 LOCAL <domain>
2. 1002 REMOTE <domain>

[edit] Queue "Callback" Commands

This command set is used by agents when the queue connects to them, to process mail waiting in the queue.

[edit] QABRT

Description: Abort a queue entry we were in the process of creating.

Syntax: QABRT

Results:

1. 1000 OK

[edit] QADDM

Description: Add something to a queue entry (FIXME)

Syntax: QADDM <queue>-<id> <sender> <authsender> <recipient> <mailbox> <flags>

Results:

1. 1000 OK
2. 4120 Mailbox locked
3. 5220 User over quota

[edit] QADDQ

Description: Add something to a queue entry (FIXME)

Syntax: QADDQ <queue>-<id> <start> <length>

Results:

1. 1000 Entry made
2. 3010 Bad arguments
3. 4224 Can't read queue entry
4. 4260 No such queue entry
5. 5221 Disk space low

[edit] QBODY

Description: Retrieve the message body from a queue entry

Syntax: QBODY <queue>-<id>

Results:

1. 1000 OK
2. 2023 <bytes> Message body follows
3. 3010 Bad arguments
4. 4224 Can't read queue entry

[edit] QBRAW

Description: Retrieve part of the message body from a queue entry

Syntax: QBRAW <queue>-<id> <start> <length>

Results:

1. 1000
2. 2021 <bytes> Partial body follows
3. 4224 Can't read queue entry

[edit] QCOPY

Description: Copy a queue entry into a new entry

Syntax: QCOPY <queue>-<id> [<target-queue>]

Results:

1. 1000 OK
2. 3010 Bad arguments
3. 4000 Target queue out of range
4. 4224 Can't read queue entry
5. 4226 Queue entry still open
6. 5221 Disk space low

[edit] QCREA

Description: Create new queue entry

Syntax: QCREA [<target-queue>]

Results:

1. 1000 Entry made
2. 3010 Bad arguments
3. 4000 Target queue out of range
4. 5221 Disk space low

[edit] QDELE

Description: Delete a queue entry

Syntax: QDELE <queue>-<id>

Results:

1. 1000 Entry removed
2. 3010 Bad arguments

[edit] QDONE

Description: Finished processing queue work (FIXME)

Syntax: QDONE

Results:

1. 1000 OK

[edit] QDSPC

Description: Ask the queue how much disk space is available

Syntax: QDSPC

Results:

1. 1000 <bytes> free

[edit] QGREP

Description: Find a field within a queue entry

Syntax: QGREP <queue>-<id> <field>

Results:

1. 1000 OK
2. 2002-<field contents>
3. 3010 Bad arguments
4. 4224 Cannot read queue entry

[edit] QHEAD

Description: Fetch the mail headers from a queue entry

Syntax: QHEAD <queue>-<id>

Results:

1. 1000 OK
2. 2023 <bytes> Message header follows
3. 3010 Bad arguments
4. 4224 Cannot read queue entry

[edit] QINFO

Description: Get information about a queue entry (FIXME)

Syntax: QINFO <queue>-<id>

Results:

1. 2001 <queue>-<id> <size> <header-size> <body-size> 0 0 0 0
2. 4224 Cannot read queue entry

[edit] QMIME

Description: Get a MIME report for a queue entry (FIXME)

Syntax: QMIME <queue>-<id>

Results:

SendMIME() in queue

[edit] QMOD FROM

Description: Set the sender on the open queue entry (FIXME)

Syntax: QMOD FROM <sender>

Results:

1. ???

[edit] QMOD FLAGS

Description: Set the flags on the open queue entry (FIXME)

Syntax: QMOD FLAGS <flags>

Results:

1. ???

[edit] QMOD LOCAL

Description: Set a local recipient on the open queue entry (FIXME)

Syntax: QMOD LOCAL <recipient>

Results:

1. ???

[edit] QMOD MAILBOX

Description: Set which mailbox folder to deliver the open queue entry to (FIXME)

Syntax: QMOD MAILBOX <mailbox>

Results:

1. ???

[edit] QMOD RAW

Description: ??? (FIXME)

Syntax: QMOD RAW <something>

Results:

1. ???

[edit] QMOD TO

Description: Set a remote recipient on the open queue entry (FIXME)

Syntax: QMOD TO <address>

Results:

1. ???

[edit] QMOVE

Description: Move a queue entry to another queue

Syntax: QMOVE <queue>-<id> <target-queue>

Results:

1. 1000 OK
2. 3010 Bad arguments
3. 4224 No such queue entry

[edit] QRCP

Description: Close the open queue entry, duplicating it into a new (open) entry, and process the old entry (FIXME)

Syntax: QRCP

Results:

1. 1000 OK
2. 3010 Bad arguments
3. 4000 Can't unlock entry
4. 5221 Disk space low

[edit] QRETR

Description: Return a queue entry to sender (FIXME)

Syntax: QRET <queue>-<id> [INFO|MESSAGE]

Results:

1. 1000 OK
2. 2022 <bytes> INFO follows
3. 2023 <bytes> MESSAGE follows
4. 3010 Bad arguments
5. 4224 Can't read queue entry

[edit] QRTS

Description: Return the open queue entry to sender (FIXME)

Syntax: QRTS <recipient> <original address> <envelope flags> [<delivery state>] [<transcript>]

Results:

1. 3012 Bad queue state

FIXME: This command doesn't seem to return anything on success; can anyone verify this in the code? Perhaps this is never used??

[edit] QRUN

Description: Run queue entries (FIXME: how is this different to flush?)

Syntax: QRUN [<queue>-<id>]

Results:

1. 1000 <queue>-<id> OK
2. 3010 Bad arguments

[edit] Queue "Search" Commands

[edit] QSRCH DOMAIN

Description: Look for a domain in the queue cache?? (FIXME)

Syntax: QSRCH DOMAIN <domain>

Results:

1. 1000 OK
2. 3010 Bad arguments
3. 4261 Domain not in cache
4. 5230 Out of memory

[edit] QSRCH HEADER

Description: Search a queue entry mail header for a field and content

Syntax: QSRCH HEADER <queue>-<id> <field> <content>

Results:

1. 1000 Content found
2. 3010 Bad arguments
3. 4224 Can't read queue entry
4. 4262 Content not found

[edit] QSRCH BODY

Description: Search a queue entry mail body for a string

Syntax: QSRCH BODY <queue>-<id> <needle>

Results:

1. 1000 Content found
2. 3010 Bad arguments
3. 4224 Can't read queue entry
4. 4262 Content not found

[edit] QSRCH BRAW

Description: Search a certain byte range within a queue entry mail body for a string

Syntax: QSRCH BRAW <queue>-<id> <start> <end> <needle>

Results:

1. 1000 Content found
2. 3010 Bad arguments
3. 4224 Can't read queue entry
4. 4262 Content not found

[edit] Queue "Store" Commands

These commands act identically to their QMOD counterparts, but act on the open queue entry, not any general queue entry.

[edit] QSTOR ADDRESS

[edit] QSTOR CAL

[edit] QSTOR FLAGS

[edit] QSTOR FROM

[edit] QSTOR LOCAL

[edit] QSTOR MESSAGE

[edit] QSTOR RAW

[edit] QSTOR TO