diff options
Diffstat (limited to 'docs/man')
-rw-r--r-- | docs/man/Makefile.am | 2 | ||||
-rw-r--r-- | docs/man/pkaction.xml | 3 | ||||
-rw-r--r-- | docs/man/pkcheck.xml | 3 | ||||
-rw-r--r-- | docs/man/pkexec.xml | 3 | ||||
-rw-r--r-- | docs/man/pkttyagent.xml | 154 | ||||
-rw-r--r-- | docs/man/polkit.xml | 15 |
6 files changed, 180 insertions, 0 deletions
diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am index 076608b..b71c1d2 100644 --- a/docs/man/Makefile.am +++ b/docs/man/Makefile.am @@ -10,6 +10,7 @@ man_MANS = \ pkexec.1 \ pkcheck.1 \ pkaction.1 \ + pkttyagent.1 \ $(NULL) %.8 %.1 : %.xml @@ -24,6 +25,7 @@ EXTRA_DIST = \ pkexec.xml \ pkcheck.xml \ pkaction.xml \ + pkttyagent.xml \ $(NULL) clean-local: diff --git a/docs/man/pkaction.xml b/docs/man/pkaction.xml index ba91e9a..24c156f 100644 --- a/docs/man/pkaction.xml +++ b/docs/man/pkaction.xml @@ -100,6 +100,9 @@ </citerefentry>, <citerefentry> <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum> </citerefentry> </para> </refsect1> diff --git a/docs/man/pkcheck.xml b/docs/man/pkcheck.xml index bb5866d..6b8a874 100644 --- a/docs/man/pkcheck.xml +++ b/docs/man/pkcheck.xml @@ -213,6 +213,9 @@ KEY3=VALUE3 </citerefentry>, <citerefentry> <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum> </citerefentry> </para> </refsect1> diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml index 8196511..1734033 100644 --- a/docs/man/pkexec.xml +++ b/docs/man/pkexec.xml @@ -283,6 +283,9 @@ </citerefentry>, <citerefentry> <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum> </citerefentry> </para> </refsect1> diff --git a/docs/man/pkttyagent.xml b/docs/man/pkttyagent.xml new file mode 100644 index 0000000..f0f328e --- /dev/null +++ b/docs/man/pkttyagent.xml @@ -0,0 +1,154 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "../version.xml"> +]> +<refentry id="pkttyagent.1" xmlns:xi="http://www.w3.org/2003/XInclude"> + <refentryinfo> + <title>pkttyagent</title> + <date>May 2009</date> + <productname>polkit</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>pkttyagent</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="version"></refmiscinfo> + </refmeta> + + <refnamediv> + <refname>pkttyagent</refname> + <refpurpose>Textual authentication helper</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>pkttyagent</command> + <arg><option>--version</option></arg> + <arg><option>--help</option></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>pkttyagent</command> + + <group> + <arg choice="plain"> + <option>--process</option> + <group choice="req"> + <arg choice="plain"> + <replaceable>pid</replaceable> + </arg> + <arg choice="plain"> + <replaceable>pid,pid-start-time</replaceable> + </arg> + </group> + </arg> + <arg choice="plain"> + <option>--system-bus-name</option> + <replaceable>busname</replaceable> + </arg> + </group> + + <group> + <arg choice="plain"> + <option>--notify-fd</option> + <replaceable>fd</replaceable> + </arg> + </group> + + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1 id="pkttyagent-descsription"> + <title>DESCRIPTION</title> + <para> + <command>pkttyagent</command> is used to start a textual + authentication agent for the subject specified by either + <option>--process</option> or + <option>--system-bus-name</option>. If neither of these options + are given, the parent process is used. + </para> + <para> + To get notified when the authentication agent has been + registered either listen to the <link + linkend="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">Changed</link> + D-Bus signal or use <option>--notify-fd</option> to pass the + number of a file descriptor that has been passed to the + program. This file descriptor will then be closed when the + authentication agent has been successfully registered. + </para> + </refsect1> + + <refsect1 id="pkttyagent-return-value"> + <title>RETURN VALUE</title> + <para> + If the authentication agent could not be registered, + <command>pkttyagent</command> exits with an exit code of + 127. Diagnostic messages are printed on standard error. + </para> + <para> + If one or more of the options passed are malformed, + <command>pkttyagent</command> exits with an exit code of 126. If + stdin is a tty, then this manual page is also shown. + </para> + <para> + If the authentication agent was successfully registered, + <command>pkttyagent</command> will keep running, interacting + with the user as needed. When its services are no longer needed, + the process can be killed. + </para> + </refsect1> + + <refsect1 id="pkttyagent-notes"> + <title>NOTES</title> + <para> + Since process identifiers can be recycled, the caller should + always use <replaceable>pid,pid-start-time</replaceable> when + using the <option>--process</option> option. The value of + <replaceable>pid-start-time</replaceable> can be determined by + consulting e.g. the + <citerefentry> + <refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> + file system depending on the operating system. If only <replaceable>pid</replaceable> + is passed to the <option>--process</option> option, then <command>pkttyagent</command> + will look up the start time itself but note that this may be racy. + </para> + </refsect1> + + <refsect1 id="pkttyagent-author"><title>AUTHOR</title> + <para> + Written by David Zeuthen <email>davidz@redhat.com</email> with + a lot of help from many others. + </para> + </refsect1> + + <refsect1 id="pkttyagent-bugs"> + <title>BUGS</title> + <para> + Please send bug reports to either the distribution or the + polkit-devel mailing list, + see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/> + on how to subscribe. + </para> + </refsect1> + + <refsect1 id="pkttyagent-see-also"> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry> diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml index ae67f7c..188c514 100644 --- a/docs/man/polkit.xml +++ b/docs/man/polkit.xml @@ -223,6 +223,18 @@ System Context | | implemention for systems without a <literal>root</literal> account. </para> + + <para> + Applications that do not run under a desktop environment (for + example, if launched from a + <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry> + login) may not have have an authentication agent associated with + them. Such applications may use the <link + linkend="PolkitAgentTextListener-struct">PolkitAgentTextListener</link> + type or the + <citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + helper so the user can authenticate using a textual interface. + </para> </refsect1> <refsect1 id="polkit-declaring-actions"><title>DECLARING ACTIONS</title> @@ -469,6 +481,9 @@ System Context | | <citerefentry> <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum> </citerefentry>, + <citerefentry> + <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum> + </citerefentry> </para> </refsect1> </refentry> |