dbuspolicy-finder documentation

Change-Id: Ia6617d124a4e4da8a1377eefba2b70b971b65c23

diff --git a/src/documentation.txt b/src/documentation.txt
new file mode 100644 (file)
index 0000000..89ee5b3
--- /dev/null
+++ b/src/documentation.txt
@@ -0,0 +1,115 @@
+DESCRIPTION:
+dbuspolicy-finder is the libdbuspolicy filtering tool. See http://www.freedesktop.org/software/dbus/ for more information about the big picture.
+A message bus daemon has a configuration file that specializes it for a particular application.
+For example, one configuration file might set up the message bus to be a systemwide message bus, while another might set it up to be a per-user-login-session bus.
+There are two standard configuration files: 'system.conf' and 'session.conf', but users can choose their own configuration file.
+
+The <policy> element has one of three attributes:
+- context="(default|mandatory)"
+- user="username or userid"
+- group="group name or gid"
+
+This program prints matching rules from all the contexts: 'default', 'user', 'group' and 'mandatory' in the order of evaluation.
+
+There are two modes:
+- where specific filter options are provided (printing matching rules);
+- only group, user or even no options are provided (printing all the rules from the context).
+
+OPTIONS:
+User must provide both: policy type (send | receive | own | access) and the configuration file. Otherwise, program will ask for it and show help.
+Additionaly, user can choose from the following arguments:
+
+Options for 'send':
+
+       -t, --type=TYPE    The default type is ANY; type="method_call" | "method_return" | "signal" | "error"
+
+       -g, --group=GROUP  It is possible to limit found records to the only one group. You can use both: names or digits; group="groupname"
+
+       -u, --user=USER    It is possible to limit found records to the only one user. You can use both: names or digits; user="username"
+
+       -n, --name         It is the destination, where message should be send; it matches to send_destination attribute; name="service_name"
+
+       -i, --interface    It is an interface; it matches to send_interface attribute; interface="interface_name"
+
+       -p, --path         It is a path to the dbus object; it matches to send_path attribute; path="/path/name"
+
+       -m, --member       It is a member; it matches to send_member attribute; it matches to member="method_or_signal_name"
+
+
+Options for 'receive':
+
+       -t, --type=TYPE    The default type is ANY; type="method_call" | "method_return" | "signal" | "error"
+
+       -g, --group=GROUP  It is possible to limit found records to the only one group. You can use both: names or digits; group="groupname"
+
+       -u, --user=USER    It is possible to limit found records to the only one user. You can use both: names or digits; user="username"
+
+       -n, --name         It is the sender, from which message came; it matches to receive_sender attribute; name="sender_name"
+
+       -i, --interface    It is an interface; it matches to receive_interface attribute; interface="interface_name"
+
+       -p, --path         It is a path to the dbus object; it matches to receive_path attribute; path="/path/name"
+
+       -m, --member       It is a member; it matches to receive_member attribute; member="method_or_signal_name"
+
+
+Options for 'access':
+
+       -g, --group=GROUP  It is possible to limit found records to the only one group. You can use both: names or digits; group="groupname"
+
+       -u, --user=USER    It is possible to limit found records to the only one user. You can use both: names or digits; user="username"
+
+
+Options for 'own':
+
+       -g, --group=GROUP  It is possible to limit found records to the only one group. You can use both: names or digits; group="groupname"
+
+       -u, --user=USER    It is possible to limit found records to the only one user. You can use both: names or digits; user="username"
+
+       -n, --name         It is a well-known bus name; name="service_name"
+
+
+EXAMPLES:
+$ dbuspolicy-finder send -c configuration_file.conf --group 7 --interface org.bluez
+//you can provide your configuration file
+
+
+$ dbuspolicy-finder receive --session --group lp
+
+       Context Default:
+ItemReceive: name(), inter(), member(), path(), type(METHOD_CALL), decision(ALLOW)
+ItemReceive: name(), inter(), member(), path(), type(METHOD_RETURN), decision(ALLOW)
+ItemReceive: name(), inter(), member(), path(), type(SIGNAL), decision(ALLOW)
+ItemReceive: name(), inter(), member(), path(), type(ERROR), decision(ALLOW)
+ItemReceive: name(), inter(org.tizen.data_control_service), member(), path(), type(SIGNAL), decision(CHECK:http://tizen.org/privilege/datasharing)
+No rules for group in policy!
+
+
+$ dbuspolicy-finder send --session --user root --interface org.bluez
+
+       Context Default:
+ItemSend: name(), inter(), member(), path(), type(ANY), decision(ALLOW)
+ItemSend: name(), inter(), member(), path(/org/tizen/messageport), type(ANY), decision(ALLOW)
+No rules for user in policy!
+
+
+$ echo "Rejected send message, 2 matched rules; type=\"method_call\", sender=\":1.26\" (uid=551 pid=2808 comm=\"\") interface=\"net.weconn.Manager\" member=\"GetState\" error name=\"(unset)\" requested_reply=\"0\" destination=\"net.weconn\" privilege=\"(n/a)\" (uid=551 pid=2786 comm=\"\")"| dbuspolicy-finder send --session --error
+
+       Context Default:
+ItemSend: name(), inter(), member(), path(), type(ANY), decision(ALLOW)
+ItemSend: name(), inter(), member(), path(/org/tizen/messageport), type(ANY), decision(ALLOW)
+
+
+$ dbuspolicy-finder send --system -t method_call -n org.tizen.system.vibrator
+
+       Context Default:
+ItemSend: name(org.tizen.system.vibrator), inter(), member(), path(), type(ANY), decision(DENY)
+ItemSend: name(org.tizen.system.vibrator), inter(), member(), path(/Org/Tizen/System/Vibrator/Haptic), type(ANY), decision(CHECK:http://tizen.org/privilege/haptic)
+       User: 0
+ItemSend: name(org.tizen.system.vibrator), inter(), member(), path(), type(ANY), decision(ALLOW)
+
+
+$ dbuspolicy-finder access --system
+
+       Context Default
+ItemAccess: type(ALL_USERS), uid(0), gid(0), decision(ALLOW)