jsoninfo: HTTP headers with CORS (if requested)
[olsrd.git] / lib / jsoninfo / README_JSONINFO
1
2 The jsoninfo plugin aims to deliver all of the information about the
3 runtime status and configuration of olsrd.  You can request specific
4 chunks of information, or overviews of runtime or startup
5 configuration, or all of the information in one report. Additionally,
6 the jsoninfo plugin will dump the current olsrd config in the
7 olsrd.conf format.  The jsoninfo plugin provides all of the
8 information that both the txtinfo and httpinfo plugins provide, as
9 well as quite a bit more.
10
11 There is a Java library called OlsrInfo that provides Java classes for
12 parsing the data from jsoninfo (and txtinfo also).  It is based on the
13 Jackson JSON processing library
14
15 OlsrInfo: https://github.com/guardianproject/OlsrInfo
16 Jackson JSON: http://jackson.codehaus.org/
17
18 PLUGIN USAGE
19 ============
20
21 There are a number of commands for getting information from this
22 plugin.  They are designed to be tacked onto a URL, but can also be
23 sent directly via a network socket. The commands are similar to the
24 txtinfo plugin, but not exactly the same.
25
26 If there is no command or no recognized command, then it sends the
27 /status output, which is the combination of /neighbors, /links,
28 /routes, /hna, /mid, /topology, /gateways, and /interfaces.
29
30 grouped information:
31 * /all - all of the data in JSON format
32 * /runtime - all of the data that reflects the runtime status of olsrd and the mesh
33 * /startup - all of the data about the startup configuration
34
35 runtime information:
36 * /neighbors (including 2-hop)
37 * /links
38 * /routes
39 * /hna
40 * /mid
41 * /topology
42 * /gateways
43 * /interfaces
44 * /status - data that changes during runtime (all above commands combined)
45
46 start-up information:
47 * /config - the current configuration, i.e. what was loaded from the olsrd.conf
48 * /plugins - currently loaded plugins and their config parameters
49
50 start-up information not in JSON format:
51 * /olsrd.conf - the current config, formatted for writing directly to /etc/olsrd.conf
52
53
54 PLUGIN CONFIGURATION
55 ====================
56
57 The plugin accepts two parameters: "port" and "accept". There are no
58 futher parameters.  Here's an example configuration for UNIX systems
59 (for Windows, change the plugin to end in .dll):
60
61 LoadPlugin "olsrd_jsoninfo.so.0.0"
62 {
63     # the default port is 9090 but you can change it like this:
64     #PlParam     "port"   "8080"
65
66     # You can set a "accept" single address to allow to connect to
67     # jsoninfo. If no address is specified, then localhost (127.0.0.1)
68     # is allowed by default.  jsoninfo will only use the first "accept"
69     # parameter specified and will ignore the rest.
70
71     # to allow a specific host:
72     #PlParam      "accept" "172.29.44.23"
73     # if you set it to 0.0.0.0, it will accept all connections
74     #PlParam      "accept" "0.0.0.0"
75
76     # The "httpheaders" parameter prepends HTTP headers to the reply.
77     # If not set it will default to "no" and have the same behaviour as before.
78     # Among with a minimal set of headers also Cross-origin resource sharing
79     # headers (CORS) are included in reply allowing the json retrieval by
80     # javascript applications not served by olsrd itself.
81     # You can enable it uncommenting the following line:
82     #PlParam      "httpheaders" "yes"
83
84     # specify a UUID for this node to track it for debugging
85     #PlParam      "UUIDFile" "/etc/olsrd/olsrd.uuid"
86 }
87
88
89 Example Usage
90 =============
91
92 You can use http URLs with various web tools to access the information:
93
94   curl http://localhost:9090/all
95
96 You can combine the various commands to generate a custom report:
97
98   curl http://localhost:9090/interfaces/routes/links
99
100 If you want a copy of the current configuration, you can download it
101 using this URL:
102
103   wget http://localhost:9090/olsrd.conf