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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title xmlns:d="http://docbook.org/ns/docbook">Fedora Cookbook</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="publican v4.1.3" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="Documentation-Fedora_Cookbook-0.1-en-US-0.0-1" /><meta name="description" content="The Fedora Cookbook contains a collection of tutorials and short guides. The book is designed to encourage community participation; submissions are welcome and the Fedora Docs community provides review and pubishing. If you would like an addition to this guide, you can request or get help to write it." /></head><body><p id="title"><a class="left" href="http://www.fedoraproject.org"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="http://docs.fedoraproject.org"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><div xml:lang="en-US" class="book" lang="en-US"><div class="titlepage"><div><div class="producttitle" font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><span xmlns:d="http://docbook.org/ns/docbook" class="productname">Documentation</span> <span xmlns:d="http://docbook.org/ns/docbook" class="productnumber">0.1</span></div><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><h1 class="title"><a id="idp1434813460"></a>Fedora Cookbook</h1></div><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><h2 class="subtitle">A collection of tutorials for Fedora</h2></div><p xmlns:d="http://docbook.org/ns/docbook" class="edition">Edition 0</p><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><h3 class="corpauthor">
<span class="inlinemediaobject"><object data="Common_Content/images/title_logo.svg" type="image/svg+xml"><img src="Common_Content/images/title_logo.png" alt="" /></object></span>
</h3></div><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><div xml:lang="en-US" class="authorgroup" lang="en-US"><div class="author"><h3 class="author"><span class="firstname">Pete</span> <span class="surname">Travis</span></h3><div class="affiliation"><span xmlns:d="http://docbook.org/ns/docbook" class="orgname">Fedora Project</span></div><code class="email"><a class="email" href="mailto:immanetize AT fedoraproject.org">immanetize AT fedoraproject.org</a></code></div></div></div><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><div class="legalnotice"><a id="idp1440201300"></a><h1 class="legalnotice">Legal Notice</h1><div class="para">
Copyright <span class="trademark"></span>© 2014 | You need to change the HOLDER entity in the en-US/Fedora_Cookbook.ent file |.
</div><div class="para">
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at <a href="http://creativecommons.org/licenses/by-sa/3.0/">http://creativecommons.org/licenses/by-sa/3.0/</a>. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
</div><div class="para">
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
</div><div class="para">
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
</div><div class="para">
For guidelines on the permitted uses of the Fedora trademarks, refer to <a href="https://fedoraproject.org/wiki/Legal:Trademark_guidelines">https://fedoraproject.org/wiki/Legal:Trademark_guidelines</a>.
</div><div class="para">
<span class="trademark">Linux</span>® is the registered trademark of Linus Torvalds in the United States and other countries.
</div><div class="para">
<span class="trademark">Java</span>® is a registered trademark of Oracle and/or its affiliates.
</div><div class="para">
<span class="trademark">XFS</span>® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
</div><div class="para">
<span class="trademark">MySQL</span>® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
</div><div class="para">
All other trademarks are the property of their respective owners.
</div></div></div><div font-family="sans-serif,Symbol,ZapfDingbats" font-weight="bold" font-size="12pt" text-align="center"><div class="abstract"><p class="title"><strong>Abstract</strong></p><div class="para">
The Fedora Cookbook contains a collection of tutorials and short guides. The book is designed to encourage community participation; submissions are welcome and the Fedora Docs community provides review and pubishing. If you would like an addition to this guide, you can request or get help to write it.
</div></div></div></div></div><div class="toc"><dl class="toc"><dt><span class="preface"><a href="#pref-Documentation-Fedora_Cookbook-Preface">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp1433629356">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp1438097324">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="#idp1432960756">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="#idp1441578996">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="#idp1436238996">2. We Need Feedback!</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Documentation-Fedora_Cookbook-Test_Chapter">1. Documenting Fedora</a></span></dt><dd><dl><dt><span class="section"><a href="#writing_recipes">1.1. Writing Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#writing_recipes-ingredients">1.1.1. Required Ingredients</a></span></dt><dt><span class="section"><a href="#writing_recipes-directions">1.1.2. Directions</a></span></dt><dt><span class="section"><a href="#idp1438639932">1.1.3. References</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#appe-Documentation-Fedora_Cookbook-Revision_History">A. Revision History</a></span></dt><dt><span class="chapter"><a href="#Storage">2. Storage</a></span></dt><dt><span class="chapter"><a href="#Productivity">3. Productivity</a></span></dt><dd><dl><dt><span class="section"><a href="#task_managing">3.1. Managing tasks using Taskwarrior</a></span></dt><dd><dl><dt><span class="section"><a href="#task_managing-ingredients">3.1.1. Required Ingredients</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Communications">4. Communications</a></span></dt><dd><dl><dt><span class="section"><a href="#Communications-IRC">4.1. Internet Relay Chat</a></span></dt><dd><dl><dt><span class="section"><a href="#bip">4.1.1. Installing the <code class="systemitem">bip</code> IRC Proxy</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Multimedia">5. Multimedia</a></span></dt><dt><span class="chapter"><a href="#Networking">6. Networking</a></span></dt><dt><span class="chapter"><a href="#Cloud">7. Cloud</a></span></dt><dt><span class="chapter"><a href="#Virtualization">8. Virtualization</a></span></dt><dd><dl><dt><span class="section"><a href="#access-to-libvirt-without-root-privileges">8.1. Access to libvirt without root privileges</a></span></dt><dd><dl><dt><span class="section"><a href="#required-ingredients">8.1.1. Required Ingredients</a></span></dt><dt><span class="section"><a href="#creating-a-name_of_article">8.1.2. Create polkit policy for libvirt</a></span></dt><dt><span class="section"><a href="#idp1431394564">8.1.3. References</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Security">9. Security</a></span></dt><dt><span class="index"><a href="#idp1429424036">Index</a></span></dt></dl></div><div xml:lang="en-US" class="preface" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="pref-Documentation-Fedora_Cookbook-Preface"></a>Preface</h1></div></div></div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="idp1433629356">
</a>1. Document Conventions</h2></div></div></div><div class="para">
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
</div><div class="para">
In PDF and paper editions, this manual uses typefaces drawn from the <a href="https://fedorahosted.org/liberation-fonts/">Liberation Fonts</a> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.
</div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="idp1438097324">
</a>1.1. Typographic Conventions</h3></div></div></div><div class="para">
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
</div><div class="para">
<code class="literal">Mono-spaced Bold</code>
</div><div class="para">
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
To see the contents of the file <code class="filename">my_next_bestselling_novel</code> in your current working directory, enter the <code class="command">cat my_next_bestselling_novel</code> command at the shell prompt and press <span class="keycap"><strong>Enter</strong></span> to execute the command.
</div></blockquote></div><div class="para">
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
</div><div class="para">
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Press <span class="keycap"><strong>Enter</strong></span> to execute the command.
</div><div class="para">
Press <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>F2</strong></span> to switch to a virtual terminal.
</div></blockquote></div><div class="para">
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
</div><div class="para">
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in <code class="literal">mono-spaced bold</code>. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
File-related classes include <code class="classname">filesystem</code> for file systems, <code class="classname">file</code> for files, and <code class="classname">dir</code> for directories. Each class has its own associated set of permissions.
</div></blockquote></div><div class="para">
<span class="application"><strong>Proportional Bold</strong></span>
</div><div class="para">
This denotes words or phrases encountered on a system, including application names; dialog-box text; labeled buttons; check-box and radio-button labels; menu titles and submenu titles. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Choose <span class="guimenu"><strong>System</strong></span> → <span class="guisubmenu"><strong>Preferences</strong></span> → <span class="guimenuitem"><strong>Mouse</strong></span> from the main menu bar to launch <span class="application"><strong>Mouse Preferences</strong></span>. In the <span class="guilabel"><strong>Buttons</strong></span> tab, select the <span class="guilabel"><strong>Left-handed mouse</strong></span> check box and click <span class="guibutton"><strong>Close</strong></span> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
</div><div class="para">
To insert a special character into a <span class="application"><strong>gedit</strong></span> file, choose <span class="guimenu"><strong>Applications</strong></span> → <span class="guisubmenu"><strong>Accessories</strong></span> → <span class="guimenuitem"><strong>Character Map</strong></span> from the main menu bar. Next, choose <span class="guimenu"><strong>Search</strong></span> → <span class="guimenuitem"><strong>Find…</strong></span> from the <span class="application"><strong>Character Map</strong></span> menu bar, type the name of the character in the <span class="guilabel"><strong>Search</strong></span> field and click <span class="guibutton"><strong>Next</strong></span>. The character you sought will be highlighted in the <span class="guilabel"><strong>Character Table</strong></span>. Double-click this highlighted character to place it in the <span class="guilabel"><strong>Text to copy</strong></span> field and then click the <span class="guibutton"><strong>Copy</strong></span> button. Now switch back to your document and choose <span class="guimenu"><strong>Edit</strong></span> → <span class="guimenuitem"><strong>Paste</strong></span> from the <span class="application"><strong>gedit</strong></span> menu bar.
</div></blockquote></div><div class="para">
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
</div><div class="para">
<code class="command"><em class="replaceable">Mono-spaced Bold Italic</em></code> or <span class="application"><strong><em class="replaceable">Proportional Bold Italic</em></strong></span>
</div><div class="para">
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
To connect to a remote machine using ssh, type <code class="command">ssh <em class="replaceable">username</em>@<em class="replaceable">domain.name</em></code> at a shell prompt. If the remote machine is <code class="filename">example.com</code> and your username on that machine is john, type <code class="command">ssh john@example.com</code>.
</div><div class="para">
The <code class="command">mount -o remount <em class="replaceable">file-system</em></code> command remounts the named file system. For example, to remount the <code class="filename">/home</code> file system, the command is <code class="command">mount -o remount /home</code>.
</div><div class="para">
To see the version of a currently installed package, use the <code class="command">rpm -q <em class="replaceable">package</em></code> command. It will return a result as follows: <code class="command"><em class="replaceable">package-version-release</em></code>.
</div></blockquote></div><div class="para">
Note the words in bold italics above: username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
</div><div class="para">
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Publican is a <em class="firstterm">DocBook</em> publishing system.
</div></blockquote></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="idp1432960756">
</a>1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
Terminal output and source code listings are set off visually from the surrounding text.
</div><div class="para">
Output sent to a terminal is set in <code class="computeroutput">mono-spaced roman</code> and presented thus:
</div><pre class="screen">books Desktop documentation drafts mss photos stuff svn
books_tests Desktop1 downloads images notes scripts svgs</pre><div class="para">
Source-code listings are also set in <code class="computeroutput">mono-spaced roman</code> but add syntax highlighting as follows:
</div><pre xml:lang="en-US" class="programlisting" lang="en-US">package org.<span class="perl_Function">jboss</span>.<span class="perl_Function">book</span>.<span class="perl_Function">jca</span>.<span class="perl_Function">ex1</span>;
<span class="perl_Keyword">import</span> javax.naming.InitialContext;
<span class="perl_Keyword">public</span> <span class="perl_Keyword">class</span> ExClient
{
<span class="perl_Keyword">public</span> <span class="perl_DataType">static</span> <span class="perl_DataType">void</span> <span class="perl_Function">main</span>(String args[])
<span class="perl_Keyword">throws</span> Exception
{
InitialContext iniCtx = <span class="perl_Keyword">new</span> InitialContext();
Object ref = iniCtx.<span class="perl_Function">lookup</span>(<span class="perl_String">"EchoBean"</span>);
EchoHome home = (EchoHome) ref;
Echo echo = home.<span class="perl_Function">create</span>();
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Created Echo"</span>);
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Echo.echo('Hello') = "</span> + echo.<span class="perl_Function">echo</span>(<span class="perl_String">"Hello"</span>));
}
}</pre></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="idp1441578996">
</a>1.3. Notes and Warnings</h3></div></div></div><div class="para">
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
</div><div xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
</div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="important"><div class="admonition_header"><p><strong>Important</strong></p></div><div class="admonition"><div class="para">
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled “Important” will not cause data loss but may cause irritation and frustration.
</div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="warning"><div class="admonition_header"><p><strong>Warning</strong></p></div><div class="admonition"><div class="para">
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
</div></div></div></div></div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="idp1436238996">
</a>2. We Need Feedback!</h2></div></div></div><a id="idp1438716612" class="indexterm"></a><div class="para">
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: <a href="http://bugzilla.redhat.com/bugzilla/">http://bugzilla.redhat.com/bugzilla/</a> against the product <span class="application"><strong>Fedora Documentation.</strong></span>
</div><div class="para">
When submitting a bug report, be sure to mention the manual's identifier: <em class="citetitle">cookbook</em>
</div><div class="para">
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
</div></div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="chap-Documentation-Fedora_Cookbook-Test_Chapter">
</a>Chapter 1. Documenting Fedora</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#writing_recipes">1.1. Writing Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#writing_recipes-ingredients">1.1.1. Required Ingredients</a></span></dt><dt><span class="section"><a href="#writing_recipes-directions">1.1.2. Directions</a></span></dt><dt><span class="section"><a href="#idp1438639932">1.1.3. References</a></span></dt></dl></dd></dl></div><div class="para">
This chapter explains how to write documentation for Fedora, such as submissions to this guide.
</div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="writing_recipes">
</a>1.1. Writing Recipes</h2></div></div></div><div class="para">
Writing recipes for the Fedora Cookbook is easy! Use a provided template to get started, submit your tutorial to the Fedora Documentation team for review, and we'll publish.
</div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="writing_recipes-ingredients">
</a>1.1.1. Required Ingredients</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
<span class="emphasis"><em>Article template</em></span> from <a href="https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/examples">the provided examples.</a>
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>Your favorite text editor.</em></span> You can use whatever you prefer, but please save them as a plain text file instead of a binary format such as <code class="literal">ODF</code>
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>A topic</em></span>. You will need something to write the tutorial about!
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>A reviewer</em></span>. When you submit your tutorial, a Fedora Docs team member will help you review the content to make sure it is clear and understandable.
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>A license</em></span>. We need your permission to distribute your work and help keep it up to date.
</div></li></ul></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="writing_recipes-directions">
</a>1.1.2. Directions</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="procedure"><a id="idp1427778668">
</a><p class="title"><strong>Procedure 1.1. Creating a New Tutorial</strong></p><ol class="1"><li class="step"><div class="para">
Choose a topic. The focus of the article should be clear, and you should be able to achieve the goal in a short series of steps. If the process is complex, consider splitting into a series of smaller articles.
</div><div class="important"><div class="admonition_header"><p><strong>Write about Fedora!</strong></p></div><div class="admonition"><div class="para">
Fedora Documentation should be only cover capabilities that Fedora can provide. Fedora is about free software, and the docs should be as free as the code.
</div><div class="para">
Submissions that require software not available in Fedora should be avoided. Tutorials that require software that is <a href="https://fedoraproject.org/wiki/Forbidden_itemshttps://fedoraproject.org/wiki/Forbidden_items">not permissible</a> for Fedora cannot be accepted.
</div></div></div></li><li class="step"><div class="para">
Download a template from <a href="https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/examples">the repository</a> maintained by the Fedora Docs team. Choose the format you like, then click <span class="guilabel"><strong>plain</strong></span> to get it in a format you can cut and paste into an editor.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
An introduction.
</div></li><li class="listitem"><div class="para">
A list of <code class="literal">ingredients</code> required to complete the tutorial
</div></li><li class="listitem"><div class="para">
The procedural instructions.
</div></li><li class="listitem"><div class="para">
References to resources or other content on the same subject.
</div></li></ul></div><div class="para">
You can submit your tutorials in any understandable format. Eventually, it will be converted to DocBook, but the content is more important than the format. Choose a format you are comfortable with.
</div></li><li class="step"><div class="para">
Write an introduction to your tutorial. It doesn't need to be long, but the reader should have a good idea of the results.
</div></li><li class="step"><div class="para">
Write an outline of the procedure you want to document. This outline doesn't need to be detailed yet, just give an overview of the steps needed.
</div></li><li class="step"><div class="para">
Follow your outline and fill in the details. Start with the minimum acceptable configuration, and add the minimal configuration to the <code class="literal">ingredients</code> list.
</div><div class="para">
If possible, you should use a virtual machine or a clean user account. You can miss important steps because of local changes to installed packages or user configuration files.
</div></li><li class="step"><div class="para">
Make sure that your directions achieve the desired result. If there are steps that would be better in a seperate recipe, you should reference the other recipe. If it doesn't exist, you can write that first or request that it be written.
</div></li><li class="step"><div class="para">
Update your ingredients list with the requirements you found when testing the instructions.
</div></li><li class="step"><div class="para">
License your content. If you have an FAS account and have agreed to the <a href="https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement">Fedora Contributor Agreement</a>, that's good enough. This defaults to <a href="http://creativecommons.org/licenses/by-sa/3.0/legalcode">CC-BY-SA</a>, used by most Fedora Documentation.
</div><div class="para">
If you want to use another license, you must declare it. The license must allow redistribution and modification, at least for non-commercial purposes. If you have questions about licensing, ask.
</div></li><li class="step"><div class="para">
Submit your tutorial to the <a href="https://admin.fedoraproject.org/mailman/listinfo/docs-qa">Fedora Docs Quality Assurance mailing list</a> for review.
</div><div class="para">
Fedora Docs volunteers will check over your tutorial and work with you to improve it. We want to teach you how to write good content, just like you want to help users with the subject of the tutorial.
</div></li><li class="step"><div class="para">
After the review, a Fedora Docs volunteer will help find the best place for your content. Most <code class="literal">recipes</code> will probably end up in the <em class="citetitle">Fedora Cookbook</em>, but you might want to write for one of the more formal Guides at <a href="http://docs.fedoraproject.org/">http://docs.fedoraproject.org/</a>
</div><div class="para">
The guide will also be submitted for translation, so Fedora's users around the globe can benefit. See <a href="https://fedoraproject.org/wiki/L10N">https://fedoraproject.org/wiki/L10N</a> for more information about the Fedora Localization project.
</div></li></ol></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="idp1438639932">
</a>1.1.3. References</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
<a href="http://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/Documentation_Guide/index.html">Fedora Documentation Guide</a>
</div></li></ul></div></div></div></div><div xml:lang="en-US" class="appendix" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="appe-Documentation-Fedora_Cookbook-Revision_History"></a>Revision History</h1></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="para"><p></p>
<div class="revhistory"><table summary="Revision History"><tr><th align="left" valign="top" colspan="3"><strong>Revision History</strong></th></tr><tr><td align="left">Revision 0.0-1</td><td align="left">Sat Mar 22 2014</td><td align="left"><span class="author"><span class="firstname">Pete</span> <span class="surname">Travis</span></span></td></tr><tr><td align="left" colspan="3">
<table border="0" summary="Simple list" class="simplelist"><tr><td>member</td></tr></table>
</td></tr></table></div>
</div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Storage">
</a>Chapter 2. Storage</h1></div></div></div><div class="para">
</div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Productivity">
</a>Chapter 3. Productivity</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#task_managing">3.1. Managing tasks using Taskwarrior</a></span></dt><dd><dl><dt><span class="section"><a href="#task_managing-ingredients">3.1.1. Required Ingredients</a></span></dt></dl></dd></dl></div><div class="para">
</div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="task_managing">
</a>3.1. Managing tasks using Taskwarrior</h2></div></div></div><div class="para">
Taskwarrior is an open-source cross platform command-line task management tool that allows you to easily capture, annotate, manipulate and present your tasks as well as sync them among your devices. In this recipe, we see how to set up a Taskwarrior server and a set of clients.
</div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="task_managing-ingredients">
</a>3.1.1. Required Ingredients</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
<span class="emphasis"><em>taskd</em></span> from the Fedora repositories - sudo yum install taskd
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>task</em></span> from the Fedora repositories - sudo yum install task
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>vit</em></span> - optional - from the Fedora repositories - sudo yum install vit
</div></li><li class="listitem"><div class="para">
<span class="emphasis"><em>Your favorite text editor.</em></span> You can use whatever you prefer, but please save them as a plain text file instead of a binary format such as <code class="literal">ODF</code>
</div></li></ul></div></div></div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Communications">
</a>Chapter 4. Communications</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#Communications-IRC">4.1. Internet Relay Chat</a></span></dt><dd><dl><dt><span class="section"><a href="#bip">4.1.1. Installing the <code class="systemitem">bip</code> IRC Proxy</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="Communications-IRC">
</a>4.1. Internet Relay Chat</h2></div></div></div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="bip">
</a>4.1.1. Installing the <code class="systemitem">bip</code> IRC Proxy</h3></div></div></div><div class="para">
Internet Relay Chat, or IRC, is a venerable and popular way to communicate over the internet. Fedora users can <a href="https://fedoraproject.org/wiki/Communicating_and_getting_help#IRC_for_interactive_community_support">get help</a> on IRC, and many other open source projects use it to collaborate. IRC is accessed using an <span class="emphasis"><em>IRC Client</em></span>, and clients are available for almost every platform, including <code class="systemitem">Windows</code>, <code class="systemitem">OS X</code>, <code class="systemitem">Android</code>, <code class="systemitem">iOS</code>, and of course every Linux distribution.
</div><a id="idp1429777204" class="indexterm"></a><div class="para">
An IRC Proxy, or <em class="firstterm">bouncer</em>, connects to an IRC server just like any other client. Rather than presenting the connection in a chat window, the <span class="application"><strong>bouncer</strong></span> relays the connection to other clients. You can connect multiple clients to the same bouncer, allowing conversations to remain uninterrupted as you move between devices. The bouncer also keeps logs, and replays recent conversations when you connect, so you can catch up after being away.
</div><div class="para">
The <code class="systemitem">bip</code> is easy to install and configure in Fedora. Follow the instructions below, and you'll be up and running in just a few minutes.
</div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h4 class="title"><a id="bip-ingredients">
</a>4.1.1.1. Required Ingredients</h4></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
Seperate machines for the IRC proxy and client.
</div><div class="para">
This ingredient is optional; you can use bip on the same system as the client to keep logs, or a persistent IRC session while switching users or logging out. <code class="systemitem">bip</code> is most useful when run on a seperate server, and can work on even low power devices like a <span class="hardware">Raspberry Pi</span> or other ARM device.
</div></li><li class="listitem"><div class="para">
An active internet connection.
</div></li><li class="listitem"><div class="para">
The <span class="package">bip</span> package.
</div></li><li class="listitem"><div class="para">
An IRC Client.
</div><div class="para">
Fedora offers many IRC clients, and the right one is a matter of personal preference. If you are new to IRC, try starting with <span class="application"><strong>hexchat</strong></span>.
</div></li><li class="listitem"><div class="para">
tcp port 7778 set to forward to your <code class="systemitem">bip</code> server.
</div><div class="para">
This is <span class="emphasis"><em>only</em></span> needed if you want to use the server when outside your home network.
</div></li></ul></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h4 class="title"><a id="bip-directions">
</a>4.1.1.2. Directions</h4></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="procedure"><a id="idp1436668932">
</a><p class="title"><strong>Procedure 4.1. Installing and Configuring <code class="systemitem">bip</code></strong></p><ol class="1"><li class="step"><div class="para">
Install required packages on the server:
</div><pre class="screen">
<code class="command">yum install bip</code>
</pre></li><li class="step"><div class="para">
Use the <span class="application"><strong>bipgenconfig</strong></span> utility to generate a configuration file.
</div><div class="para">
In this example, you will configure the <a href="http://freenode.net/">freenode</a> IRC network. Fedora's IRC channels are on Freenode.
</div><ol class="substeps a"><li class="step"><div class="para">
Start <span class="application"><strong>bipgenconfig</strong></span> from a terminal.
</div><pre class="screen">
<code class="command">bipgenconfig</code>
<code class="computeroutput"> # This script will help you build a configuration file # # WARNING: non-advanced mode, some 'expert' options'll be hidden ! # 1. Set global options 2. Add a new network 3. Add a new user 4. View global options 5. View/Edit/Delete networks 6. View/Edit/Delete users 7. Generate a server certificate/key pair 8. Switch to advanced mode 10. Exit: store, write configuration and exit 11. Exit without saving 12. Store configuration for later use 20. Reset config options 21. Load stored config 22. Parse and load current config (todo) What do you want to do ? </code>
</pre></li><li class="step"><div class="para">
Enter the system wide settings dialog by pressing <span class="keycap"><strong>1</strong></span> and <span class="keycap"><strong>Enter</strong></span>
</div><pre class="screen">
<code class="computeroutput"> * Do you want to enable channel logging ? [Y/n] y * Do you want to enable system logging ? [Y/n] y * In which directory do you want logs to be stored ? [/home/pete/.bip/logs] /var/log/bip/ </code>
</pre><div class="para">
Logging is turned on here, and logs are sent to the system log directory.
</div></li><li class="step"><div class="para">
Back at the main menu, press <span class="keycap"><strong>2</strong></span> and <span class="keycap"><strong>Enter</strong></span> to create a network definition.
</div><pre class="screen"><code class="computeroutput"> * Network's name <em class="replaceable">freenode</em> * Enable SSL for this network ? [y/N] <em class="replaceable">n</em> Adding a new server : * IRC server's IP address/hostname <em class="replaceable">irc.freenode.net</em> * IRC server's port [6667] <em class="replaceable">6667</em> Do you want to add a new server ? [Y/n] <em class="replaceable">n</em> </code></pre></li><li class="step"><div class="para">
The <code class="function">Add a new user</code> section at option <span class="keycap"><strong>3</strong></span> is where you configure your user for bip, the connections bip will provide to that user, and the user's accounts on the previously configured networks.
</div><pre class="screen"><code class="computeroutput"> * User's internal name ? fedorauser Set a password for his bip account: ? Password: * User's default IRC nickname fedorauser * User's default IRC username fedorauser * User's default IRC realname Fedora B User * Do you want to activate backlog {play back logs} system ? [Y/n] y </code></pre><div class="para">
The options above are for your user account with bip. The password is hashed when stored, and does not appear on the screen when typed.
</div><pre class="screen"><code class="computeroutput"> Adding a new connection : * Connection name (used by bip only) <em class="replaceable">freenode</em> * Network to connect to freenode * Use default identity ? [Y/n] y * IRC server's password ? <em class="replaceable">fedorauser</em>:<em class="replaceable">freenode-nickserv-password</em> </code></pre><div class="para">
In this section, you have created a <code class="function">connection</code> for the freenode network that was defined in an earlier step. Freenode accepts authentication to a registered nick by a server password like the one in the example. While the configuration file will only be readable by root on the server, this password is stored in plain text.
</div><pre class="screen"><code class="computeroutput"> * Follow nicknames changes from clients to use upon reconnection (if false, bip'll use config nickname) [Y/n] n * Ignore nickname change sent by a client (first one only, upon client attach) [Y/n] y * Set nickname to this value when there's no more client attached: fedorauser * Set this away message when there's no more client attached: * Send this raw message upon connection to IRC server </code></pre><div class="para">
These options are set to retain the configured user name as much as possible. It is generally considered good IRC ediquette to avoid adding noise by changing your nick often.
</div><pre class="screen"><code class="computeroutput"> Adding a new channel : * Channel name #fedora * Channel key (optional) Do you want to add a new channel ? [Y/n] y Adding a new channel : * Channel name #fedora-docs * Channel key (optional) Do you want to add a new channel ? [Y/n] n Do you want to add a new connection ? [Y/n] n </code></pre><div class="para">
Configure the channels you would like to automatically join, and enter the channel password if required. <code class="systemitem">bip</code> will connect to these channels when it starts. If you join additional channels, bip can keep them open for you, but they will not be rejoined if the service is restarted.
</div></li><li class="step"><div class="para">
Select option <span class="keycap"><strong>10</strong></span> after reviewing your configuration to save and exit.
</div><pre class="screen"><code class="computeroutput"> Configuration stored in /home/pete/.bip/bipgenconfig.store Configuration saved in /home/pete/.bip/bip.conf.autogen 1 users defined, 1 networks defined Configuration has been generated in /home/pete/.bip/bip.conf.autogen You have to rename all generated files to use them </code></pre></li><li class="step"><div class="para">
Copy the new configuration file to the appropriate path and set ownership.
</div><pre class="screen">
<code class="command"> sudo cp /home/fedorauser/.bip/bip.conf.autogen /etc/ </code>
<code class="command"> sudo chown root:bip /etc/bip.conf </code>
<code class="command"> sudo chmod 0640 /etc/bip.conf </code>
</pre></li></ol></li><li class="step"><div class="para">
Activate the bip service:
<pre class="screen">
<code class="command">systemctl start bip</code>
<code class="command">systemctl enable bip</code>
</pre>
</div></li><li class="step"><div class="para">
Configure your IRC client to use the bip service.
</div><div class="para">
This example is for <span class="application"><strong>HexChat</strong></span>. To configure other clients, refer to that client's documentation.
</div><ol class="substeps a"><li class="step"><div class="para">
Launch <span class="application"><strong>hexchat</strong></span> and open the Network List by clicking <span class="guimenuitem"><strong>Hexchat</strong></span> then <span class="guimenuitem"><strong>Network List...</strong></span>.
</div></li><li class="step"><div class="para">
Click the <span class="guibutton"><strong>Add</strong></span> button in the Network List window.
</div><div class="para">
A new network item is immediately added to the <span class="guilabel"><strong>Networks</strong></span>. Type in a name for your network, such as <em class="replaceable">Fedorauser's BIP server</em>.
</div></li><li class="step"><div class="para">
Click <span class="guibutton"><strong>Edit...</strong></span> to enter more details for the connection.
</div><ol class="substeps i"><li class="step"><div class="para">
Click <span class="guibutton"><strong>Add</strong></span> to add an address for your server. A new entry will immediately be created for editing in the list.
</div><div class="para">
Enter your server's IP address and the port number. It should look something like this:
</div><pre class="screen">
<code class="systemitem">192.168.1.72</code>/7778
</pre></li><li class="step"><div class="para">
Enter your bip user information in the <span class="guilabel"><strong>Password:</strong></span>. The form is <span class="emphasis"><em>bip_username:bip_connection:bip_user_password</em></span>. To use the freenode connection from the earlier steps, this would be:
</div><pre class="screen">
fedorauser:freenode:<em class="replaceable">bip_user_password</em>
</pre></li><li class="step"><div class="para">
If you choose, checking the box for <span class="guilabel"><strong>Connect to this network automatically</strong></span> will configure hexchat to connect to your bouncer every time hexchat is opened.
</div></li></ol></li></ol></li></ol></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h4 class="title"><a id="idp1436085988">
</a>4.1.1.3. References</h4></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
<a href="http://example.com">Upstream Documentation</a>
</div></li><li class="listitem"><div class="para">
<a href="http://example.com/myblog/posts/todays_date">http://example.com/myblog/posts/todays_date</a>
</div></li></ul></div></div></div></div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Multimedia">
</a>Chapter 5. Multimedia</h1></div></div></div><div class="para">
</div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Networking">
</a>Chapter 6. Networking</h1></div></div></div><div class="para">
</div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Cloud">
</a>Chapter 7. Cloud</h1></div></div></div><div class="para">
</div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Virtualization">
</a>Chapter 8. Virtualization</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="#access-to-libvirt-without-root-privileges">8.1. Access to libvirt without root privileges</a></span></dt><dd><dl><dt><span class="section"><a href="#required-ingredients">8.1.1. Required Ingredients</a></span></dt><dt><span class="section"><a href="#creating-a-name_of_article">8.1.2. Create polkit policy for libvirt</a></span></dt><dt><span class="section"><a href="#idp1431394564">8.1.3. References</a></span></dt></dl></dd></dl></div><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title"><a id="access-to-libvirt-without-root-privileges">
</a>8.1. Access to libvirt without root privileges</h2></div></div></div><div class="para">
By default, only root can administer virtual machines using libvirt. Use these instructions to create a special group whose members will be able to use libvirt.
</div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="required-ingredients">
</a>8.1.1. Required Ingredients</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
Package 'polkit'
</div></li><li class="listitem"><div class="para">
Package 'libvirt'
</div></li></ul></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="creating-a-name_of_article">
</a>8.1.2. Create polkit policy for libvirt</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="procedure"><ol class="1"><li class="step"><div class="para">
Create polkit policy for libvirt:
</div><pre class="screen">
<code class="command"> touch /etc/polkit-1/localauthority/50-local.d/50-org.libvirt-group-access.pkla </code>
</pre></li><li class="step"><div class="para">
Open the policy file in an editor.
</div><pre class="screen">
<code class="command"> $EDITOR /etc/polkit-1/localauthority/50-local.d/50-org.libvirt-group-access.pkla </code>
</pre></li><li class="step"><div class="para">
Paste in the rule below.
</div><pre class="screen">
[libvirt group Management Access]
Identity=unix-group:libvirt
Action=org.libvirt.unix.manage
ResultAny=yes
ResultInactive=yes
ResultActive=yes
</pre></li><li class="step"><div class="para">
Create group for users that can access libvirt without root privileges:
</div><pre class="screen">
<code class="command"> groupadd libvirt </code>
</pre></li><li class="step"><div class="para">
Add your users to the special group:
</div><pre class="screen">
<code class="command"> usermod -a -G libvirt user_name </code>
</pre></li></ol></div></div><div class="section"><div class="titlepage"><div><div keep-together.within-column="always"><h3 class="title"><a id="idp1431394564">
</a>8.1.3. References</h3></div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
<a href="http://wiki.libvirt.org/page/SSHPolicyKitSetup#Configuration_for_group_access">Libvirt policykit documentation</a>
</div></li></ul></div></div></div></div><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="Security">
</a>Chapter 9. Security</h1></div></div></div><div class="para">
</div></div><div class="index"><div class="titlepage"><div><div><h1 class="title"><a id="idp1429424036">
</a>Index</h1></div></div></div><div class="index"><div class="indexdiv"><h3>B</h3><dl><dt>bouncer, <a class="indexterm" href="#bip">Installing the bip IRC Proxy</a></dt></dl></div><div class="indexdiv"><h3>F</h3><dl><dt>feedback</dt><dd><dl><dt>contact information for this manual, <a class="indexterm" href="#idp1436238996">We Need Feedback!</a></dt></dl></dd></dl></div></div></div></div></body></html>
|
