summaryrefslogtreecommitdiffstats
path: root/docs/func.pod
blob: 7d5684a41eb90958246e34d4dcacd5e2677777e5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
=head1 NAME

Func -- Fedora Unified Network Controller.

=head1 SYNOPSIS

func "*" list_minons

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 --memory

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