X-Git-Url: https://pwan.org/git/?p=certmaster.git;a=blobdiff_plain;f=docs%2Ffunc.pod;fp=docs%2Ffunc.pod;h=5ee594b10b22c56c6f00b03e91418be1bf7eb8e4;hp=0000000000000000000000000000000000000000;hb=697402da24ca930b3608359a61b9872fdddc62d9;hpb=ac3061bcffd2ea634596c188beaa13339e3fa24a

diff --git a/docs/func.pod b/docs/func.pod
new file mode 100644
index 0000000..5ee594b
--- /dev/null
+++ b/docs/func.pod
@@ -0,0 +1,111 @@
+=head1 NAME
+
+Func -- Fedora Unified Network Controller.
+
+=head1 SYNOPSIS
+
+func "*" list_minions
+
+func target.example.org call module method [args ...]
+
+func "target*.example.org" call module method [args ...]
+
+func "webserver1;mailserver2" call module method [args ...]
+
+=head1 DESCRIPTION
+
+"func" allows remote control of machines running funcd (called "minions")
+that are set to obey this machine (called the "overlord").  This includes
+performing various remote operations and gathering data.
+
+"func" can address multiple machines at the same time by specifying
+their names with globs, which follow shell glob syntax.
+
+See the project homepage (below) for a list of modules available
+and a more in-depth description of what each of them do.
+
+=head1 THE "CALL" MODULE
+
+The "call" module is used for running func modules remotely.  
+
+Format:  func "*.example.org" call <module> <function> [ args ... ]
+
+=head1 LISTING REMOTE MODULES AVAILABLE
+
+It's possible to ask func minions what modules they have installed:
+
+func "*.example.org" call system list_modules
+
+=head1 LISTING REMOTE FUNCTIONS AVAILABLE IN A MODULE
+
+It is also possible to ask remote func modules what functions they support:
+
+func target.example.org call modulename list_methods
+
+=head1 CALLING A REMOTE COMMAND
+
+Once you have the name of a module you want to run, use call to invoke it:
+
+func target.example.org call modulename methodname
+
+=head1 OUTPUT FORMATS
+
+The "call" command by default outputs data using a "pretty printer".  Other
+display options include --raw, --json, and --xmlrpc, which may be more
+desirable if you are running func inside another script or prefer to read
+those display formats.
+
+Example: func "*" call --json service inventory
+
+
+=head1 HELPER MODULES
+
+In addition to "call", there are other modules that make control of remote
+machines, as well as data display, more user friendly.  They augment "call"
+by providing some additional functionality.
+
+You will notice that the syntax for using one of these helper modules
+varies slightly from just using "call" directly.
+
+For example "show" can be used to show remote data.  The normal command "func '*'
+command would dump a very large amount of data, while the show command can mine
+only a few details.  This might make things more readable, for instance, when
+not going through the Python API (where you would not care). 
+
+func "*.example.org" show hardware --help
+
+func "*.example.org" show hardware systemMemory
+
+func "*.example.org" show hardware os
+
+Another useful helper command module is copyfile, which allows func to work like scp from 
+the shell, though it can address multiple systems at the same time.  
+
+The following example pushes one file out to multiple systems:
+
+func "*.example.org" copyfile --file=/tmp/foo --remotepath=/tmp/foo
+
+While these helper modules will grow over time, usage of "call" syntax 
+directly is fine also.  See the Wiki for more examples as they evolve.
+
+=head1 --verbose
+
+Use this flag to output extra information from func while it is running.
+All func commands can take this flag.
+
+=head1 EXIT_STATUS
+
+Func commands have return values that vary based on the module being
+called.  See the project page (linked below) for more information.
+
+=head1 ADDITONAL RESOURCES
+
+See https://hosted.fedoraproject.org/projects/func/ for more information, including information on scripting func from Python.
+
+See also the manpages for "func-inventory", "funcd", "certmaster", and "certmaster-ca".
+
+=head1 AUTHOR
+
+Various. See https://hosted.fedoraproject.org/projects/func
+
+