all: ensure all files have the same license header
[olsrd.git] / lib / info / README_INFO
1 =======
2 WARNING
3 =======
4
5 This is NOT a plugin.
6
7 This is common code for the jsoninfo and txtinfo plugins.
8
9
10 ============
11 INTRODUCTION
12 ============
13
14 An info plugin aims to deliver all of the information about the runtime status
15 and configuration of olsrd.
16
17 Information that can be requested:
18 * specific parts of runtime data or startup configuration
19 * overview of runtime data
20 * overview of startup configuration
21 * all of the information in one report
22
23 Additionally, an info plugin can dump the current olsrd configuration in the
24 in the olsrd.conf format.
25
26
27 ============
28 PLUGIN USAGE
29 ============
30
31 There are a number of commands for getting information from an info plugin.
32 They are designed to be part of a URL, but can also be sent directly via a
33 network socket.
34
35 If there is no command or no recognized command, then the command '/all' is
36 assumed.
37
38 Check the README of the actual info plugin to see the supported commands.
39
40
41 ====================
42 PLUGIN CONFIGURATION
43 ====================
44
45 An info plugin is configured with the generic info plugin configuration
46 parameters shown below.
47
48 The port in the generic info plugin configuration is setup by the actual
49 info plugin.
50
51 LoadPlugin "an_info_plugin.so.0.0"
52 {
53   # The port on which the info plugin will be listening
54   # PlParam "port"           "<defined by the actual info plugin>"
55
56   # Controls which IP address is allowed to connect to the info plugin.
57   # Use 0.0.0.0 to accept all connections
58   # Default: localhost (127.0.0.1 / ::1)
59   # PlParam "accept"         "127.0.0.1"
60
61   # Controls of which IP address the info plugin will listen for requests.
62   # Only the last specified setting will be used, others will be ignored.
63   # Default: any (0.0.0.0 / ::)
64   # PlParam "listen"         "0.0.0.0"
65
66   # Set to true to first send HTTP headers
67   # Default: true
68   # PlParam "httpheaders"    "true"
69
70   # Set to true to always allow connections from localhost (127.0.0.1 / ::1)
71   # Default: false
72   # PlParam "allowlocalhost" "false"
73
74   # Set to true to only listen on IPv6 addresses when running in IPv6 mode.
75   # Default: false
76   # PlParam "ipv6only"       "false"
77
78   # The time (in milliseconds) after which cached information times out.
79   # A negative value or a value of zero effectively disables caching.
80   # Caching is on by default since it provides some protection again DoS
81   # attacks, therefore it is strongly recommended to keep caching switched
82   # on by configuring a positive value here.
83   # Note: startup information (version, config and plugins) is cached forever
84   #       by default.
85   # Default: 1000
86   # PlParam "cachetimeout"       "1000"
87 }
88
89
90 =============
91 Example Usage
92 =============
93
94 The examples shown here assume an info plugin on port 9090.
95
96 Provided an info plugin is configured to send http headers (which is the
97 default case), then http URLs can be used with various web tools to access the
98 information, for example by using curl or wget (or even a web browser):
99   curl http://localhost:9090/all
100   wget http://localhost:9090/all
101
102 Commands can also be sent directly to an info plugin to access the information,
103 for example by using netcat:
104   echo "/all" | nc localhost 9090