/mandos/trunk

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/trunk
423 by Teddy Hogeborn
Documentation changes:
1
		   -*- mode: org; coding: utf-8 -*-
2
3
		    Mandos Server D-Bus Interface
4
5
This file documents the D-Bus interface to the Mandos server.
6
7
* Bus: System bus
24.1.186 by Björn Påhlsson
transitional stuff actually working
8
  Bus name: "se.recompile.Mandos"
423 by Teddy Hogeborn
Documentation changes:
9
10
11
* Object Paths:
12
  
13
  | Path                  | Object            |
14
  |-----------------------+-------------------|
15
  | "/"                   | The Mandos Server |
16
  | "/clients/CLIENTNAME" | Mandos Client     |
17
18
  
19
* Mandos Server Interface:
24.1.186 by Björn Påhlsson
transitional stuff actually working
20
  Interface name: "se.recompile.Mandos"
423 by Teddy Hogeborn
Documentation changes:
21
  
22
** Methods:
23
*** GetAllClients()  (ao: Clients)
24
    Returns an array of all client D-Bus object paths
25
   
26
*** GetAllClientsWithProperties()  (a{oa{sv}}: ClientProperties)
27
    Returns an array of all clients and all their properties
28
   
29
*** RemoveClient(o: ObjectPath)  nothing
30
    Removes a client
31
   
32
** Signals:
33
*** ClientAdded(o: ObjectPath)
34
    A new client was added.
35
   
36
*** ClientNotFound(s: Fingerprint, s: Address)
37
    A client connected from Address using Fingerprint, but was
38
    rejected because it was not found in the server.  The fingerprint
39
    is represented as a string of hexadecimal digits.  The address is
40
    an IPv4 or IPv6 address in its normal string format.
41
   
42
*** ClientRemoved(o: ObjectPath, s: Name)
43
    A client named Name on ObjectPath was removed.
44
45
46
* Mandos Client Interface:
24.1.186 by Björn Påhlsson
transitional stuff actually working
47
  Interface name: "se.recompile.Mandos.Client"
423 by Teddy Hogeborn
Documentation changes:
48
  
49
** Methods
50
*** Approve(b: Approve)  nothing
51
    Approve or deny a connected client waiting for approval.  If
52
    denied, a client will not be sent its secret.
53
    
54
*** CheckedOK()  nothing
55
    Assert that this client has been checked and found to be alive.
56
    This will restart the timeout before disabling this client.  See
57
    also the "LastCheckedOK" property.
58
59
** Properties
60
   
61
   Note: Many of these properties directly correspond to a setting in
62
   "clients.conf", in which case they are fully documented in
63
   mandos-clients.conf(5).
64
   
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
65
   | Name                    | Type | Access     | clients.conf        |
66
   |-------------------------+------+------------+---------------------|
67
   | ApprovedByDefault       | b    | Read/Write | approved_by_default |
68
   | ApprovalDelay (a)       | t    | Read/Write | approval_delay      |
69
   | ApprovalDuration (a)    | t    | Read/Write | approval_duration   |
70
   | ApprovalPending (b)     | b    | Read       | N/A                 |
71
   | Checker                 | s    | Read/Write | checker             |
72
   | CheckerRunning (c)      | b    | Read/Write | N/A                 |
73
   | Created (d)             | s    | Read       | N/A                 |
74
   | Enabled (e)             | b    | Read/Write | N/A                 |
24.1.179 by Björn Påhlsson
New feature:
75
   | Expires (f)             | s    | Read       | N/A                 |
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
76
   | ExtendedTimeout (a)     | t    | Read/Write | extended_timeout    |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
77
   | Fingerprint             | s    | Read       | fingerprint         |
78
   | Host                    | s    | Read/Write | host                |
79
   | Interval (a)            | t    | Read/Write | interval            |
24.1.179 by Björn Påhlsson
New feature:
80
   | LastApprovalRequest (g) | s    | Read       | N/A                 |
81
   | LastCheckedOK (h)       | s    | Read/Write | N/A                 |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
82
   | LastCheckerStatus (i)   | n    | Read       | N/A                 |
83
   | LastEnabled (j)         | s    | Read       | N/A                 |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
84
   | Name                    | s    | Read       | (Section name)      |
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
85
   | Secret (k)              | ay   | Write      | secret (or secfile) |
442 by Teddy Hogeborn
* DBUS-API: Document new "LastApprovalRequest" client property.
86
   | Timeout (a)             | t    | Read/Write | timeout             |
423 by Teddy Hogeborn
Documentation changes:
87
   
88
   a) Represented as milliseconds.
89
   
90
   b) An approval is currently pending.
91
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
92
   c) Changing this property can either start a new checker or abort a
93
      running one.
423 by Teddy Hogeborn
Documentation changes:
94
   
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
95
   d) The creation time of this client object, as an RFC 3339 string.
423 by Teddy Hogeborn
Documentation changes:
96
   
781 by Teddy Hogeborn
Deprecate some D-Bus methods in favor of D-Bus properties.
97
   e) Changing this property enables or disables a client.
423 by Teddy Hogeborn
Documentation changes:
98
   
24.1.179 by Björn Påhlsson
New feature:
99
   f) The date and time this client will be disabled, as an RFC 3339
518.2.3 by Teddy Hogeborn
Make "enabled" a client config option.
100
      string, or an empty string if this is not scheduled.
24.1.179 by Björn Påhlsson
New feature:
101
   
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
102
   g) The date and time of the last approval request, as an RFC 3339
103
      string, or an empty string if this has not happened.
104
   
105
   h) The date and time a checker was last successful, as an RFC 3339
106
      string, or an empty string if this has not happened.  Setting
107
      this property is equivalent to calling CheckedOK(), i.e. the
108
      current time is set, regardless of the string sent.  Please
109
      always use an empty string when setting this property, to allow
110
      for possible future expansion.
111
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
112
   i) The exit status of the last checker, -1 if it did not exit
113
      cleanly, -2 if a checker has not yet returned.
114
   
115
   j) The date and time this client was last enabled, as an RFC 3339
497 by Teddy Hogeborn
* DBUS-API: Document new "Expires" and "ExtendedTimeout" properties.
116
      string, or an empty string if this has not happened.
423 by Teddy Hogeborn
Documentation changes:
117
   
556 by Teddy Hogeborn
* DBUS-API (se.recompile.Mandos.Client.LastCheckerStatus): New
118
   k) A raw byte array, not hexadecimal digits.
423 by Teddy Hogeborn
Documentation changes:
119
120
** Signals
783 by Teddy Hogeborn
Revert change to D-Bus API.
121
*** CheckerCompleted(n: Exitcode, x: Waitstatus, s: Command)
423 by Teddy Hogeborn
Documentation changes:
122
    A checker (Command) has completed.  Exitcode is either the exit
783 by Teddy Hogeborn
Revert change to D-Bus API.
123
    code or -1 for abnormal exit.  In any case, the full Waitstatus
124
    (as from wait(2)) is also available.
423 by Teddy Hogeborn
Documentation changes:
125
    
126
*** CheckerStarted(s: Command)
127
    A checker command (Command) has just been started.
128
    
129
*** GotSecret()
130
    This client has been sent its secret.
131
    
132
*** NeedApproval(t: Timeout, b: ApprovedByDefault)
133
    This client will be approved or denied in exactly Timeout
134
    milliseconds, depending on ApprovedByDefault.  Approve() can now
135
    usefully be called on this client object.
477 by Teddy Hogeborn
* DBUS-API: Fix grammar.
136
    
423 by Teddy Hogeborn
Documentation changes:
137
*** Rejected(s: Reason)
138
    This client was not given its secret for a specified Reason.
139
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
140
* Copyright
141
749.1.1 by Teddy Hogeborn
mandos: Use multiprocessing module to run checkers.
142
    Copyright © 2010-2015 Teddy Hogeborn
143
    Copyright © 2010-2015 Björn Påhlsson
444 by Teddy Hogeborn
Update copyright year to "2010" wherever appropriate.
144
  
145
** License:
146
   
147
   This program is free software: you can redistribute it and/or
148
   modify it under the terms of the GNU General Public License as
149
   published by the Free Software Foundation, either version 3 of the
150
   License, or (at your option) any later version.
151
152
   This program is distributed in the hope that it will be useful, but
153
   WITHOUT ANY WARRANTY; without even the implied warranty of
154
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
155
   General Public License for more details.
156
157
   You should have received a copy of the GNU General Public License
158
   along with this program.  If not, see
159
   <http://www.gnu.org/licenses/>.
160
423 by Teddy Hogeborn
Documentation changes:
161

162
#+STARTUP: showall