From 8f2ff4d7c902d534d68ff1a16418b7be492033bf Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Thu, 7 Feb 2008 13:13:24 -0500 Subject: Carving away at func some more to just get down to cert items, still lots more to do. --- docs/certmaster-ca.pod | 13 ++---- docs/certmaster-request.pod | 36 ++++++++++++++ docs/certmaster.pod | 15 +++--- docs/func-inventory.pod | 70 ---------------------------- docs/func.pod | 111 -------------------------------------------- docs/funcd.pod | 25 ---------- 6 files changed, 48 insertions(+), 222 deletions(-) create mode 100644 docs/certmaster-request.pod delete mode 100644 docs/func-inventory.pod delete mode 100644 docs/func.pod delete mode 100644 docs/funcd.pod (limited to 'docs') diff --git a/docs/certmaster-ca.pod b/docs/certmaster-ca.pod index fce3f73..0b95b4a 100644 --- a/docs/certmaster-ca.pod +++ b/docs/certmaster-ca.pod @@ -12,10 +12,7 @@ certmaster-ca --sign machine.example.org "certmaster-ca --list" -The list command prints all certificates that have been requested from certmaster by a remote -service (such as funcd) but are not yet signed. - -func commands can't be sent to a remote machine until the certificates have been signed. +The list command prints all certificates that have been requested from certmaster by a remote application (such as funcd or certmaster-request) but are not yet signed. "certmaster-ca --sign [hostname]" @@ -26,16 +23,16 @@ This command is used to sign a certificate and send it back to the requester. The certmaster can be configured to make this command unneccessary; all incoming requests can be signed automatically by certmaster. -To configure this, edit /etc/func/certmaster.conf. +To configure this, edit /etc/certmaster/certmaster.conf. =head1 ADDITONAL RESOURCES -See https://hosted.fedoraproject.org/projects/func/. It's a Wiki. +See https://fedorahosted.org/certmaster. It's a Wiki. -See also the manpages for "func", "func-inventory", "funcd", and "certmaster". +See also the manpages for "certmaster" and "certmaster-request". =head1 AUTHOR -Various. See https://hosted.fedoraproject.org/projects/func +Various. See https://fedorahosted.org/certmaster diff --git a/docs/certmaster-request.pod b/docs/certmaster-request.pod new file mode 100644 index 0000000..1a7bf4a --- /dev/null +++ b/docs/certmaster-request.pod @@ -0,0 +1,36 @@ +=head1 NAME + +certmaster-request -- requests SSL certs from a certmasster +Fedora Unified Network Controller. + +=head1 SYNOPSIS + +certmaster-request [--server certmaster.example.com] [--port port] +[ --wait infinite/seconds ] + +=head1 DESCRIPTION + +FIXME: To be added later once we split this out from func. + +=head1 API + +Note: Many applications will want to use the XMLRPC API (see source) or import +the Python code to request certs. For those that don't want to do that, +this command line tool is available. Explore the other options if they +make more sense for your application. + +=head1 EXIT_STATUS + +non-zero upon failure. + +=head1 ADDITONAL RESOURCES + +See https://fedorahosted.org/certmaster for more information + +See also the manpages for "certmaster", and "certmaster-ca". + +=head1 AUTHOR + +Various. See https://fedorahosted.org/func + + diff --git a/docs/certmaster.pod b/docs/certmaster.pod index 92f5074..08985cf 100644 --- a/docs/certmaster.pod +++ b/docs/certmaster.pod @@ -1,6 +1,7 @@ =head1 NAME -certmaster -- hands out certificates to funcd and other components. +certmaster -- hands out certificates to programs that want them, like +certmaster-request or users of the certmaster API =head1 SYNOPSIS @@ -8,19 +9,17 @@ certmaster (it's a daemon and takes no arguments) =head1 DESCRIPTION -See https://hosted.fedoraproject.org/projects/func/ +See https://fedorahosted.org/certmaster -Certmaster is run on the master-control machine on a network being -controlled by func. It hands out certificates to machines running -funcd. +Certmaster is a daemon that runs on a "master" machine to hand out certificates to machines that want them. Certificates can then be used by applications like func. -Certmaster is configured by /etc/func/certmaster.conf +Certmaster is configured by /etc/certmaster/certmaster.conf =head1 ADDITONAL RESOURCES -See https://hosted.fedoraproject.org/projects/func/. It's a Wiki. +See https://fedorahosted.org/certmaster/. It's a Wiki. -See also the manpages for "func", "func-inventory", "funcd", "certmaster-ca". +See also the manpages for "certmaster-request" and "certmaster-ca". =head1 AUTHOR diff --git a/docs/func-inventory.pod b/docs/func-inventory.pod deleted file mode 100644 index cfe362d..0000000 --- a/docs/func-inventory.pod +++ /dev/null @@ -1,70 +0,0 @@ -=head1 NAME - -func-inventory -- Takes inventory of data from func minions, and stores them in git. - -=head1 SYNOPSIS - -func-inventory [--verbose] [--server-spec glob] [--methods list] [--modules list] [--tree path] [--no-git] - -=head1 DESCRIPTION - -func-inventory runs against func-minions to gather information, and stores this information on the filesystem, in a tree arranged by hostname, module name, and method name. - -After each update, differences are commited to version control (using git), where they can be examined with tools such as "git log" and "gitk". - -=head1 --verbose - -Provides extra output about what func-inventory is doing. - -=head1 --server-spec - -A glob, as can be given to "func", that describes what machines the inventory program should run against. The default is "*". - -=head1 --modules list - -A comma-seperated list of modules that should be included in the inventory, for instance "hardware,packages". -The default is "all". - -=head1 --methods list - -A comma-seperated list of methods that should be included in the inventory, for each module being queried. The default -is "info", which saves the data for any module that has an "info" method. - -=head1 --tree-path - -Selects the location where func-inventory will output data. The default is /var/lib/func/inventory. This directory will -contain a tree structure based on the hostnames, modules, and methods included in the inventory. - -=head1 --no-git - -Disables git integration, meaning changes will not be tracked using version control. This option is present -for those that do not have the "git-core" package installed, though installing it is highly recommended to get -the full degree of power out of func-inventory. - -=head1 VIEWING CHANGES - -Since func-inventory integrates with git, all changes to the remote systems (including additions of new systems) can -be tracked using standard git-tools such as "git log" and "gitk", when run on the directory specified for --tree. - -Additional built in hooks to notify changes can be written using git's own trigger mechanism, though something -more specific to func will likely be developed in the future -- also eliminating the need to grok git internals. - -=head1 ALTERNATIVE OUTPUT FORMATS - -func-inventory can be passed a --json or --xmlrpc parameter to override the default output format. These -output formats are much less readable in the git-produced diffs, but are more easily loaded by other programs -that may want to "mine" the output of a func-inventory tree. Using --json requires that the python-simplejson -RPM be installed. - -=head1 ADDITONAL RESOURCES - -See https://hosted.fedoraproject.org/projects/func/ for more information. - -See also the manpages for "func", "funcd", "certmaster", and "certmaster-ca". - -=head1 AUTHOR - -Michael DeHaan - - - diff --git a/docs/func.pod b/docs/func.pod deleted file mode 100644 index 5ee594b..0000000 --- a/docs/func.pod +++ /dev/null @@ -1,111 +0,0 @@ -=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 [ 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 - - diff --git a/docs/funcd.pod b/docs/funcd.pod deleted file mode 100644 index da4ec75..0000000 --- a/docs/funcd.pod +++ /dev/null @@ -1,25 +0,0 @@ -=head1 NAME - -funcd -- deaemon for the Fedora Universal Network Controller - -=head1 SYNOPSIS - -funcd (it's a daemon and takes no arguments) - -=head1 DESCRIPTION - -funcd registers itself to a certificate server (certmaster) listed in /etc/func/minion.conf and takes orders from the command line func when that program is run from that certificate server. See /etc/func/minion.conf for other configuration options. - -Modules and capabilities provided by funcd are specified at https://hosted.fedoraproject.org/projects/func/ - -=head1 ADDITONAL RESOURCES - -See https://hosted.fedoraproject.org/projects/func/. It's a Wiki. - -See also the manpages for "func", "certmaster", and "certmaster-ca". - -=head1 AUTHOR - -Various. See https://hosted.fedoraproject.org/projects/func - - -- cgit