mail.medic.chalmers.se
Förstasidan-Teknikinfo-Sicconfd

Utdata och protokoll

sicconfd pratar som nämnts ett rent textbaserat protokoll. De flesta kör genom någon form av klient som oftast är ett mycket tunt lager runt textprotokollet, t.ex. för att man skall slippa skriva sitt lösenord i klartext.

Detta dokument definierar protokollet och formatet på utdatan.

Utdataformat

Enkel utdata är alltid på formen radmatningsseparerad lista. Som enkel utdata räknas allt där hela den returnerade datamängden har samma typ t.ex. en lista över mailadresser eller medlems-email i en viss maillista. Radmatningen är en \n.

Sammansatt utdata, där olika datatyper returneras samtidigt, returneras antingen i ett lätt läsbart format, eller som Colon-Separated-Values. Det lättlästa formatet är avsiktligt svårt att parsa maskinellt, och kan ändras när som helst. CSV-formatet är avsiktligt redundundant men i gengäld (förhoppningsvis) med litet behov av förändringar i framtiden, och lätt att parsa.

I CSV-formatet så får varje post i utdatan (t.ex. en maillista eller en användare beroende på vilken fråga som ställdes) en egen rad.

Exempel:

maillist:name=dtek-listan\
:member=viktor:member=d2viktor:\
:email=fubar@hotmail.com\
:description=Listan över alla \:coola\\

Detta representerar en maillista (posten har typen "maillist"). Det är en enda rad, eftersom alla newlines utom den sista är backslashade (de sista två backslasharna representerar ju en backslash i datan). Namnet är "dtek-listan". Den har två användare som medlemmar, "viktor" och "d2viktor", och en mailadress som medlem, "fubar@hotmail.com". Beskrivningen är satt till "Listan över alla :coola\".

Notera här att "\:" är ett kolon inbäddat i fältdatan, medan "\\:" skulle vara ett backslash följt av ett fältseparerande kolon. Samma sak gäller för radmatningar - ett ensamt '\' före en radmatning tar bort den, "\\" är ett backslash. "\\\:" är ett backslash följt av ett inbäddat kolon. "\\\\:" är två backslashar följt av fältseparerande kolon, o.s.v.

Textprotokollet

sicconfd lyssnar på port 7310 i klartext, dit får dock normalt bara localhost connecta. Genom en stunnel lyssnar den på port 7311 för krypterad förbindelse (accepteras från hela världen).

Börja alltså med att koppla upp till port 7311 och initiera SSL.

Din session är från början oautenticerad. För att autenticera/auktorisera använder du några av session-kommandona. Mer detaljer finns i dokumentet om autenticering och rättighetsklasser.

Därefter börjar direkt kommandoloopen. Skicka ett kommando, följt av newline. Allt efter newlinen (i alla fall i samma nätverkspaket) kastas bort, men det är inte garanterat. Skicka inget efter en newline.

Servern tuggar på ditt kommando och skickar ett svar. Svaret börjar alltid med tre siffror (statuskod), en textsträng som beskriver statuskoden i ord och sen en newline. Ibland följer ytterligare data.

Om första siffran i svarskoden är 1, så lyckades ditt kommando och ingen data behöver returneras. Dessa svar kommer på t.ex. add-, del- och set-operationer.

Om första siffran är 2, så följer data efter den första statusraden. Datan avslutas med de tre tecknena \n.\n. Formatet på datan beror av kommandot du skickade, se ovan.

Om första siffran är 5, så misslyckades kommandot, och koden berättar vad som gick fel.

När du tagit emot ett fullständigt svar från servern så kan du skicka ett nytt kommando.

Sessionen avslutas antingen genom att du bryskt stänger din nätverksförbindelse, eller ännu hellre genom att du skickar ett kommando som returnerar statuskoderna 106, 107 eller 203. Efter dessa svar kommer servern att stänga sin ände av förbindelsen.

Svarskoder

Här följer alla svarskoder och deras betydelse.

100-koder

100-koderna är enkla "ok"-koder, där all information kommer i själva koden (bortsett från 104, som duplicerar den information du redan förmodas känna till, nämligen vem du försökte autenticera dig som).

100 Ok.
Kommandot lyckades.
104 Authenticated as <uname>
Autenticeringen lyckades. Sessionen är nu autenticerad som användaren uname.
105 Server will shut down when all active sessions have finished.
sicconfd har slutat acceptera nya förbindelser, och kommer att avsluta så snart alla öppna sessioner stängts.
106 Server will shutdown when all output has been flushed. Bye.
sicconfd pressar ut all väntande utdata, och dör sedan direkt.
107 Nice talking to you. Bye.
Bekräftelse på att din session avslutats. Nätverksförbindelsen stängs direkt efter detta kommando sänts.

200-koder

200-koderna är även de ok-koder. Dock följer alltid data av någon form efter en 200-kod, denna data avslutas alltid med de tre tecknena \n.\n.

200 Data follows.
Kommandot lyckades, och data följer. Formatet på datan beror på kommandot.
203 Nice talking to you. A token of my appreciation follows.
Utloggningen lyckades. Efterföljande data är en "cookie" som kan användas för att återautenticera som samma användare inom en inte allt för lång tidsrymd.

500-koder

Det finns betydligt fler 500-koder än 100- och 200-koder. Det beror på att 500-koden innehåller exakt information om vad som gick fel.

500 Internal error.
Något hände inuti sicconfd som inte gick att hjälpa. Kan vara en bug, men beror oftast på att t.ex. databasen dött. Man bör inte få några 500, och får man det så uppskattas det om man rapporterar dem.
501 Syntax error.
Något syntaxfel på indatan, oftast ett felstavat kommando.
502 Not implemented yet.
503 You are not allowed to do that.
Antingen är sessionen oautenticerad, eller så har den användare sessionen är autenticerad som inte rätt att göra det man försökte med.
510 Authentication failed.
Kontonamn/lösenord stämde inte överens. Det skall vara ett Chalmers-ID och motsvarande lösenord från Chalmers DCE.
511 No such user.
Ett user-kommando skickades men den angivna användaren finns inte.
512 No such maillist.
Ett maillist-kommando skickades men den angivna maillistan finns inte.
513 No such domain.
Ett domain-kommando skickades men den angivna maildomänen finns inte.
514 No such localpart/address.
Ett domain <domain> address <localpart>-kommando skickades men den angivna addressen/localparten finns inte.
517 Already present.
Du försökte lägga till någonting till en lista, men det fanns redan i samma lista en gång.
518 Not present.
Du försökte ta bort något ur en lista, men det fanns inte där till att börja med.
521 Malformed user name.
522 Malformed email address.
523 Malformed address localpart.
524 Malformed date.
Datum skall anges i ISO-format, d.v.s. YYYY-MM-DD.
525 Date is in the past.
Datumet du angav ligger bakåt i tiden. Returneras t.ex. om du skall sätta en vacation.
526 Malformed integer.
527 Malformed float value.
528 Integer out of range.
529 Malformed date/time.
531 Maillist names may only contain [-a-z0-9_+:].
532 Maillists must be prefixed by "domain-" where "domain" is the prefix for a domain that you have admin privileges for (e.g. dtek- if you are admin for dtek.chalmers.se).'
En domänadministratör försökte skapa en maillista vars namn inte stämde med uppsatta regler.
533 Domain name must be a proper mail domain.
534 Addresses may only contain [-a-zA-Z0-9+_].
535 Directories' names may only contain [-a-zA-Z0-9-+:/#.] and should not end in a /.
536 Filter names may only contain [-a-zA-Z0-9+_].
537 Patterns may only contain [-a-zA-Z0-9_.*?].
539 Malformed regexp pattern.
540 Malformed filter pattern.
541 Malformed list-id.
542 Postmaster addresses are automatically created and always delivered to the domain administrators.
Du försökte skapa en "postmaster@domain"-adress.
543 owner- and -request addresses are reserved for use when maillists are bound to addresses.
544 Cannot quarantine addresses that are bound to something.
550 Password expected as last argument.
Vissa kommandon, t.ex. session auth login <uname> <password> förväntar sig ett lösenord sist. Om du skickar ett kommando utan detta lösenord så returneras denna kod, som kan trigga din klient att hämta ett lösenord med dold text, och sedan återsända samma kommando som tidigare men med lösenordet sist.