diff options
Diffstat (limited to 'markup/pod-samples/pod/live-manual/media/text')
207 files changed, 49770 insertions, 0 deletions
diff --git a/markup/pod-samples/pod/live-manual/media/text/_sisu/.empty b/markup/pod-samples/pod/live-manual/media/text/_sisu/.empty new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/_sisu/.empty diff --git a/markup/pod-samples/pod/live-manual/media/text/_sisu/css/html.css b/markup/pod-samples/pod/live-manual/media/text/_sisu/css/html.css new file mode 100644 index 0000000..d42be4d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/_sisu/css/html.css @@ -0,0 +1,1284 @@ +/* SiSU css default stylesheet */ + body { + color: black; + background: #ffffff; + background-color: #ffffff; + } + a:link { + color: #003399; + text-decoration: none; + } + a:visited { + color: #003399; + text-decoration: none; + } + a:hover { + color: #000000; + background-color: #f9f9aa; + } + a.lnkocn:link { + color: #777777; + text-decoration: none; + } + a:hover img { + background-color: #ffffff; + } + a:active { + color: #003399; + text-decoration: underline; + } + div { + margin-left: 0; + margin-right: 0; + } + div.p { + margin-left: 5%; + margin-right: 1%; + } + #top_band { + position: absolute; + top: 0; + bottom: 80px; + width: 100%; + } + #top_band_search { + position: absolute; + top: 0px; + right: 0px; + margin-left: 75%; + width: 20%; + } + #column_left { + position: absolute; + top: 80px; + left: 0; + margin-left: 1%; + width: 20%; + } + #column_center { + position: absolute; + top: 80px; + margin-left: 20%; + width: 55%; + } + #column_right { + position: absolute; + top: 80px; + right: 0px; + margin-left: 75%; + width: 25%; + } + #pane_major { + position: absolute; + top: 0px; + left: 0; + margin-left: 0; + width: 80%; + } + #pane_minor { + position: absolute; + top: 0px; + right: 0px; + margin-left: 75%; + width: 20%; + background-color: #aaaaaa; + } + .norm, .bold, .verse, .group, .block, .alt { + line-height: 133%; + margin-left: 0em; + margin-right: 2em; + margin-top: 12px; + margin-bottom: 0px; + padding-left: 0em; + text-indent: 0em; + } + p, h0, h1, h2, h3, h4, h5, h6, h7 { + display: block; + font-family: verdana, arial, georgia, tahoma, sans-serif, helvetica, times, roman; + font-size: 100%; + font-weight: normal; + line-height: 133%; + text-align: justify; + margin-left: 0em; + margin-right: 2em; + text-indent: 0mm; + margin-top: 0.8em; + margin-bottom: 0.8em; + } + /* indent */ + p.norm { } + p.i1 {padding-left: 1em;} + p.i2 {padding-left: 2em;} + p.i3 {padding-left: 3em;} + p.i4 {padding-left: 4em;} + p.i5 {padding-left: 5em;} + p.i6 {padding-left: 6em;} + p.i7 {padding-left: 7em;} + p.i8 {padding-left: 8em;} + p.i9 {padding-left: 9em;} + /* hanging indent */ + p.h0i0 { + padding-left: 0em; + text-indent: 0em; + } + p.h0i1 { + padding-left: 1em; + text-indent: -1em; + } + p.h0i2 { + padding-left: 2em; + text-indent: -2em; + } + p.h0i3 { + padding-left: 3em; + text-indent: -3em; + } + p.h0i4 { + padding-left: 4em; + text-indent: -4em; + } + p.h0i5 { + padding-left: 5em; + text-indent: -5em; + } + p.h0i6 { + padding-left: 6em; + text-indent: -6em; + } + p.h0i7 { + padding-left: 7em; + text-indent: -7em; + } + p.h0i8 { + padding-left: 8em; + text-indent: -8em; + } + p.h0i9 { + padding-left: 9em; + text-indent: -9em; + } + p.h1i0 { + padding-left: 0em; + text-indent: 1em; + } + p.h1i1 { + padding-left: 1em; + text-indent: 0em; + } + p.h1i2 { + padding-left: 2em; + text-indent: -1em; + } + p.h1i3 { + padding-left: 3em; + text-indent: -2em; + } + p.h1i4 { + padding-left: 4em; + text-indent: -3em; + } + p.h1i5 { + padding-left: 5em; + text-indent: -4em; + } + p.h1i6 { + padding-left: 6em; + text-indent: -5em; + } + p.h1i7 { + padding-left: 7em; + text-indent: -6em; + } + p.h1i8 { + padding-left: 8em; + text-indent: -7em; + } + p.h1i9 { + padding-left: 9em; + text-indent: -8em; + } + p.h2i0 { + padding-left: 0em; + text-indent: 2em; + } + p.h2i1 { + padding-left: 1em; + text-indent: 1em; + } + p.h2i2 { + padding-left: 2em; + text-indent: 0em; + } + p.h2i3 { + padding-left: 3em; + text-indent: -1em; + } + p.h2i4 { + padding-left: 4em; + text-indent: -2em; + } + p.h2i5 { + padding-left: 5em; + text-indent: -3em; + } + p.h2i6 { + padding-left: 6em; + text-indent: -4em; + } + p.h2i7 { + padding-left: 7em; + text-indent: -5em; + } + p.h2i8 { + padding-left: 8em; + text-indent: -6em; + } + p.h2i9 { + padding-left: 9em; + text-indent: -7em; + } + p.h3i0 { + padding-left: 0em; + text-indent: 3em; + } + p.h3i1 { + padding-left: 1em; + text-indent: 2em; + } + p.h3i2 { + padding-left: 2em; + text-indent: 1em; + } + p.h3i3 { + padding-left: 3em; + text-indent: 0em; + } + p.h3i4 { + padding-left: 4em; + text-indent: -1em; + } + p.h3i5 { + padding-left: 5em; + text-indent: -2em; + } + p.h3i6 { + padding-left: 6em; + text-indent: -3em; + } + p.h3i7 { + padding-left: 7em; + text-indent: -4em; + } + p.h3i8 { + padding-left: 8em; + text-indent: -5em; + } + p.h3i9 { + padding-left: 9em; + text-indent: -6em; + } + p.h4i0 { + padding-left: 0em; + text-indent: 4em; + } + p.h4i1 { + padding-left: 1em; + text-indent: 3em; + } + p.h4i2 { + padding-left: 2em; + text-indent: 2em; + } + p.h4i3 { + padding-left: 3em; + text-indent: 1em; + } + p.h4i4 { + padding-left: 4em; + text-indent: 0em; + } + p.h4i5 { + padding-left: 5em; + text-indent: -1em; + } + p.h4i6 { + padding-left: 6em; + text-indent: -2em; + } + p.h4i7 { + padding-left: 7em; + text-indent: -3em; + } + p.h4i8 { + padding-left: 8em; + text-indent: -4em; + } + p.h4i9 { + padding-left: 9em; + text-indent: -5em; + } + p.h5i0 { + padding-left: 0em; + text-indent: 5em; + } + p.h5i1 { + padding-left: 1em; + text-indent: 4em; + } + p.h5i2 { + padding-left: 2em; + text-indent: 3em; + } + p.h5i3 { + padding-left: 3em; + text-indent: 2em; + } + p.h5i4 { + padding-left: 4em; + text-indent: 1em; + } + p.h5i5 { + padding-left: 5em; + text-indent: 0em; + } + p.h5i6 { + padding-left: 6em; + text-indent: -1em; + } + p.h5i7 { + padding-left: 7em; + text-indent: -2em; + } + p.h5i8 { + padding-left: 8em; + text-indent: -3em; + } + p.h5i9 { + padding-left: 9em; + text-indent: -4em; + } + p.h6i0 { + padding-left: 0em; + text-indent: 6em; + } + p.h6i1 { + padding-left: 1em; + text-indent: 5em; + } + p.h6i2 { + padding-left: 2em; + text-indent: 4em; + } + p.h6i3 { + padding-left: 3em; + text-indent: 3em; + } + p.h6i4 { + padding-left: 4em; + text-indent: 2em; + } + p.h6i5 { + padding-left: 5em; + text-indent: 1em; + } + p.h6i6 { + padding-left: 6em; + text-indent: 0em; + } + p.h6i7 { + padding-left: 7em; + text-indent: -1em; + } + p.h6i8 { + padding-left: 8em; + text-indent: -2em; + } + p.h6i9 { + padding-left: 9em; + text-indent: -3em; + } + p.h7i0 { + padding-left: 0em; + text-indent: 7em; + } + p.h7i1 { + padding-left: 1em; + text-indent: 6em; + } + p.h7i2 { + padding-left: 2em; + text-indent: 5em; + } + p.h7i3 { + padding-left: 3em; + text-indent: 4em; + } + p.h7i4 { + padding-left: 4em; + text-indent: 3em; + } + p.h7i5 { + padding-left: 5em; + text-indent: 2em; + } + p.h7i6 { + padding-left: 6em; + text-indent: 1em; + } + p.h7i7 { + padding-left: 7em; + text-indent: 0em; + } + p.h7i8 { + padding-left: 8em; + text-indent: -1em; + } + p.h7i9 { + padding-left: 9em; + text-indent: -2em; + } + p.h8i0 { + padding-left: 0em; + text-indent: 8em; + } + p.h8i1 { + padding-left: 1em; + text-indent: 7em; + } + p.h8i2 { + padding-left: 2em; + text-indent: 6em; + } + p.h8i3 { + padding-left: 3em; + text-indent: 5em; + } + p.h8i4 { + padding-left: 4em; + text-indent: 4em; + } + p.h8i5 { + padding-left: 5em; + text-indent: 3em; + } + p.h8i6 { + padding-left: 6em; + text-indent: 2em; + } + p.h8i7 { + padding-left: 7em; + text-indent: 1em; + } + p.h8i8 { + padding-left: 8em; + text-indent: 0em; + } + p.h8i9 { + padding-left: 9em; + text-indent: -1em; + } + p.h9i0 { + padding-left: 0em; + text-indent: 9em; + } + p.h9i1 { + padding-left: 1em; + text-indent: 8em; + } + p.h9i2 { + padding-left: 2em; + text-indent: 7em; + } + p.h9i3 { + padding-left: 3em; + text-indent: 6em; + } + p.h9i4 { + padding-left: 4em; + text-indent: 5em; + } + p.h9i5 { + padding-left: 5em; + text-indent: 4em; + } + p.h9i6 { + padding-left: 6em; + text-indent: 3em; + } + p.h9i7 { + padding-left: 7em; + text-indent: 2em; + } + p.h9i8 { + padding-left: 8em; + text-indent: 1em; + } + p.h9i9 { + padding-left: 9em; + text-indent: 0em; + } + p.it0 { + margin-left: 0em; + margin-top: 6px; + margin-bottom: 0px; + line-height: 100%; + } + p.it1 { + margin-left: 1em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it2 { + margin-left: 2em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it3 { + margin-left: 3em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it4 { + margin-left: 4em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it5 { + margin-left: 5em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it6 { + margin-left: 6em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it7 { + margin-left: 7em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it8 { + margin-left: 8em; + margin-top: 0px; + margin-bottom: 0px; + line-height: 100%; + } + p.it9 { + margin-left: 9em; + margin-bottom: 0px; + margin-top: 0px; + line-height: 100%; + } + p.block { } + p.group { } + p.alt { } + p.verse { + margin-bottom: 6px; + } + p.code { + font-family: inconsolata, andale mono, courier new, courier, monospace; + font-size: 90%; + text-align: left; + background-color: #eeeeee; + } + p.caption { + text-align: left; + font-size: 80%; + display: inline; + } + p.endnote { + font-size: 96%; + line-height: 120%; + text-align: left; + margin-right: 15mm; + } + p.endnote_indent { + font-size: 96%; + line-height: 120%; + text-align: left; + margin-left: 2em; + margin-right: 15mm; + } + p.center { + text-align: center; + } + p.bold { + font-weight: bold; + } + p.bold_left { + font-weight: bold; + text-align: left; + } + p.centerbold { + text-align: center; + font-weight: bold; + } + p.em { + font-weight: bold; + font-style: normal; + background: #fff3b6; + } + p.small { + font-size: 80%; + margin-top: 0px; + margin-bottom: 0px; + margin-right: 6px; + text-align: left; + } + .tiny, .tiny_left, .tiny_right, .tiny_center { + font-size: 10px; + margin-top: 0px; + margin-bottom: 0px; + color: #777777; + margin-right: 6px; + text-align: left; + } + p.tiny { } + p.tiny_left { + margin-left: 0px; + margin-right: 0px; + text-align: left; + } + p.tiny_right { + margin-right: 1em; + text-align: right; + } + p.tiny_center { + margin-left: 0px; + margin-right: 0px; + text-align: center; + } + p.pane, p.pane_title, p.pane_blurb, p.pane_link, p.pane_indent { + font-size: 80%; + margin-top: 0px; + margin-bottom: 0px; + margin-left: 2mm; + margin-right: 4px; + text-align: left; + } + p.pane { } + p.pane_title { + font-weight: bold; + margin-bottom: 0px; + } + p.pane_blurb { + font-size: 10px; + margin-bottom: 0px; + } + p.pane_link { + font-size: 10px; + margin-bottom: 0px; + margin-left: 4mm; + } + p.pane_indent { + font-size: 10px; + margin-bottom: 0px; + margin-left: 4mm; + } + p.concordance_word { + line-height: 150%; + font-weight: bold; + display: inline; + margin-top: 4px; + margin-bottom: 1px; + } + p.concordance_count { + font-size: 80%; + color: #777777; + display: inline; + margin-left: 0em; + } + p.concordance_object { + font-size: 80%; + line-height: 120%; + text-align: left; + margin-left: 3em; + margin-top: 1px; + margin-bottom: 3px; + } + p.book_index_lev1 { + line-height: 100%; + margin-top: 4px; + margin-bottom: 1px; + } + p.book_index_lev2 { + line-height: 100%; + text-align: left; + margin-left: 3em; + margin-top: 1px; + margin-bottom: 3px; + } + p.quickref { + font-size: 10px; + font-style: italic; + margin-top: 0px; + margin-bottom: 0px; + color: #777777; + margin-right: 5px; + text-align: left; + } + p.bigref { + font-size: 11px; + font-weight: bold; + margin-top: 0px; + margin-bottom: 0px; + color: #777777; + margin-right: 5px; + text-align: center; + } + p.letter { + font-weight: bold; + font-size: 80%; + margin-left: 0em; + margin-top: 2px; + margin-bottom: 2px; + margin-right: 6px; + text-align: left; + color: white; + background: #880000; + } + tt { + font-family: inconsolata, andale mono, courier new, courier, monospace; + background-color: #eeeeee; + } + label.ocn { + width: 2%; + float: right; + top: 0; + font-size: 10px; + margin-top: 0px; + margin-bottom: 5px; + color: #777777; + margin-right: 5px; + text-align: right; + background-color: #ffffff; + } + table { } + tr { } + th,td { + vertical-align: top; + text-align: left; + } + th { + font-weight: bold; + } + p.left,th.left,td.left { + text-align: left; + } + p.small_left,th.small_left,td.small_left { + text-align: left; + font-size: 80%; + } + p.right,th.right,td.right { + text-align: right; + } + #horizontal_links { + background: #eeeeee; + margin-left: 5%; + margin-right: 5%; + } + #horizontal { + margin: 0; + padding: 0 0 0 10px; + border-top: 1px solid #000077; + border-bottom: 1px solid #000077; + } + #horizontal li { + margin: 0 0 0 0; + padding: 0 16px 0 0; + display: inline; + list-style-type: none; + text-align: left; + background: none; + } + #horizontal a { + line-height: 12px; + margin: 0 0 0 0; + text-decoration: none; + color: #000077; + } + #horizontal a.active, #horizontal a:hover { + border-bottom: 2px solid #777777; + padding-bottom: 2px; + color: #000077; + } + #horizontal a:hover { + color: #000077; + } + #document_versions { + position: absolute; + top: 10mm; + right: 2%; + width: 12%; + float: right; + } + #vertical_links { + position: absolute; + top: 10mm; + right: 0px; + width: 20%; + background: #dddddd; + float: right; + } + #vertical { + padding: 0 12px 0px 0px; + margin-left: 2%; + margin-right: 2%; + } + #vertical li { + display: block; + list-style-type: none; + } + #vertical a { + line-height: 12px; + text-decoration: none; + color: #000077; + } + #vertical a.active, #vertical a:hover { + border-bottom: 2px solid #777777; + padding-bottom: 2px; + color: #000077; + } + ul, li { + list-style-type: none; + list-style: none; + padding-left: 20px; + display: block; + font-family: verdana, arial, georgia, tahoma, sans-serif, helvetica, times, roman; + font-weight: normal; + line-height: 150%; + text-align: left; + text-indent: 0mm; + margin-left: 1em; + margin-right: 2em; + margin-top: 3px; + margin-bottom: 3px; + } + li { + background: url(../image_sys/bullet_09.png) no-repeat 0px 6px; + } + ul { + } + li.bullet { margin-left: 1em; } + li.i1 { margin-left: 2em; } + li.i2 { margin-left: 3em; } + li.i3 { margin-left: 4em; } + li.i4 { margin-left: 5em; } + li.i5 { margin-left: 6em; } + li.i6 { margin-left: 7em; } + li.i7 { margin-left: 8em; } + li.i8 { margin-left: 9em; } + li.i9 { margin-left: 10em; } + li.doc, li.ref, li.refcenter { + margin-top: 0px; + margin-bottom: 0px; + margin-right: 0px; + font-size: 8px; + font-style: normal; + text-align: left; + } + li.doc { + background: url(../image_sys/bullet_09.png) no-repeat 0px 6px; + padding-left: 16px; + margin-left: 10px; + margin-right: 0px; + } + li.ref { + background: none; + padding-left: 0; + margin-left: 0; + color: #777777; + } + li.refcenter { + background: url(../image_sys/bullet_09.png) no-repeat 0px 6px; + padding-left: 20px; + margin-left: 10%; + font-size: 9px; + color: #777777; + text-align: center; + } + li.refbold { + list-style-type: none; + padding-left: 16px; + margin-left: 0; + margin-right: 10mm; + font-weight: bold; + } + h0, h1, h2, h3, h4, h5, h6, h7 { + font-weight: bold; + line-height: 120%; + text-align: left; + margin-top: 20px; + margin-bottom: 10px; + } + h4.norm, h5.norm, h6.norm, h7.norm { + margin-top: 10px; + margin-bottom: 0px; + } + h0.center, h1.center, h2.center, h3.center, h4.center, h5.center, h6.center, h7.center { + text-align: center; + } + h0 { font-size: 125%; } + h1 { font-size: 120%; } + h2 { font-size: 115%; } + h3 { font-size: 110%; } + h4 { font-size: 105%; } + h5 { font-size: 100%; } + h6 { font-size: 100%; } + h7 { font-size: 100%; } + h1.i {margin-left: 2em;} + h2.i {margin-left: 3em;} + h3.i {margin-left: 4em;} + h4.i {margin-left: 5em;} + h5.i {margin-left: 6em;} + h6.i {margin-left: 7em;} + h7.i {margin-left: 8em;} + h8.i {margin-left: 9em;} + h9.i {margin-left: 10em;} + h1.top_band { + display: inline; + text-align: left; + margin-top: 0; + margin-left: 4mm; + text-indent: 0mm; + font-weight: bold; + font-size: 120%; + } + h2.top_band_tiny { + font-size: 10px; + font-weight: normal; + margin-top: 0px; + margin-left: 4mm; + text-indent: 0mm; + margin-bottom: 0px; + color: #777777; + margin-left: 140px; + margin-right: 0px; + text-align: left; + } + p.top_band { + display: inline; + text-align: left; + margin-top: 0; + margin-left: 140px; + text-indent: 0mm; + font-weight: bold; + font-size: 120%; + } + p.top_band_tiny { + font-size: 10px; + margin-top: 0px; + margin-bottom: 0px; + color: #777777; + margin-left: 140px; + margin-right: 0px; + text-align: left; + } + p.top_band_image { + float: left; + display: inline; + text-align: left; + margin-top: 0; + margin-left: 1mm; + text-indent: 0mm; + margin-right: 1mm; + } + .banner, .subbanner { + font-weight: bold; + text-align: center; + margin-left: 10mm; + margin-right: 15mm; + margin-top: 20px; + margin-bottom: 10px; + } + h0.banner { + font-size: 125%; + } + h1.banner { + font-size: 120%; + } + h1.subbanner { + font-size: 115%; + } + h2.banner { + font-size: 110%; + } + h3.banner { + color: #990000; + font-size: 105%; + } + h4.banner { + color: #ff0000; + font-size: 100%; + } + h5.banner { + } + h6.banner { + } + h7.banner { + } + .toc { + font-weight: normal; + margin-top: 6px; + margin-bottom: 6px; + } + h0.toc { + margin-left: 1em; + font-size: 120%; + line-height: 150%; + } + h1.toc { + margin-left: 1em; + font-size: 115%; + line-height: 150%; + } + h2.toc { + margin-left: 2em; + font-size: 110%; + line-height: 140%; + } + h3.toc { + margin-left: 3em; + font-size: 105%; + line-height: 120%; + } + h4.toc { + margin-left: 4em; + font-size: 100%; + line-height: 120%; + } + h5.toc { + margin-left: 5em; + font-size: 95%; + line-height: 110%; + } + h6.toc { + margin-left: 6em; + font-size: 90%; + line-height: 110%; + } + h7.toc { + margin-left: 7em; + font-size: 85%; + line-height: 100%; + } + .microtoc { + margin-top: 2px; + margin-bottom: 2px; + } + h0.microtoc { + margin-left: 0mm; + font-size: 120%; + } + h1.microtoc { + margin-left: 0mm; + font-size: 115%; + } + h2.microtoc { + margin-left: 5mm; + font-size: 110%; + } + h3.microtoc { + margin-left: 10mm; + font-size: 105%; + } + h4.microtoc { + margin-left: 15mm; + font-weight: normal; + font-size: 100%; + } + h5.microtoc { + margin-left: 20mm; + font-weight: normal; + font-size: 95%; + } + h6.microtoc { + margin-left: 25mm; + font-weight: normal; + font-size: 90%; + } + h7.microtoc { + margin-left: 30mm; + font-weight: normal; + font-size: 85%; + } + .subtoc { + margin-right: 34%; + font-weight: normal; + } + h5.subtoc { + margin-left: 2em; + font-size: 80%; + margin-top: 2px; + margin-bottom: 2px; + } + h6.subtoc { + margin-left: 3em; + font-size: 75%; + margin-top: 0px; + margin-bottom: 0px; + } + h7.subtoc { + margin-left: 4em; + font-size: 70%; + margin-top: 0px; + margin-bottom: 0px; + } + div.substance { + width: 100%; + background-color: #ffffff; + } + div.ocn { + width: 5%; + float: right; + top: 0; + background-color: #ffffff; + } + div.endnote { + width: 95%; + background-color: #fffffff; + } + div.toc { + position: absolute; + float: left; + margin: 0; + padding: 0; + padding-top: 0.5em; + border: 0; + width: 13em; + background-color: #eeeeee; + margin-right:1em; + } + div.summary { + margin: 0; + padding: 0; + border-left: 13em solid #eeeeee; + padding-left: 1em; + background-color: #eeeeee; + } + div.content, div.main_column { + margin: 0; + padding: 0; + border-left: 13em solid #ffffff; + padding-left: 1em; + padding-right: 1em; + } + div.content0, div.main_column0 { + margin: 0; + padding: 0; + border-left: 0% solid #ffffff; + padding-left: 5%; + } + div.scroll { + margin: 0; + padding: 0; + padding-left: 1em; + padding-right: 1em; + } + div.content:after { + content:' '; + clear:both; + display:block; + height:0; + overflow:hidden + } + div.footer { + clear:left; + padding: 0.5em; + font-size: 80%; + margin: 0; + } + div.toc ul { + list-style: none; + padding: 0; + margin: 0; + } + div.toc li ul a, li ul span.currentlink + { + font-weight: normal; + font-size: 90%; + padding-left: 2em; + background-color: #eeeeee; + } + div.toc a, span.currentlink{ + display:block; + text-decoration: none; + padding-left: 0.5em; + color: #0000aa; + } + hr { + width: 90%; + } + span.currentlink { + text-decoration: none; + background-color: #aaaaf9; + } + div.toc a:visited { + color: #0000aa; + } + div.toc a:hover { + color: #000000; + background-color: #f9f9aa; + } + .minitoc { + font-weight: normal; + margin-top: 2px; + margin-bottom: 2px; + } + h1.minitoc, h2.minitoc, h3.minitoc { + margin-left: 0em; + font-weight: bold; + text-align: left; + font-size: 90%; + margin-top: 4px; + margin-bottom: 4px; + } + h4.minitoc { + margin-left: 0em; + font-size: 90%; + } + h5.minitoc { + margin-left: 1em; + font-size: 85%; + } + h6.minitoc { + margin-left: 2em; + font-size: 85%; + } + h7.minitoc { + margin-left: 3em; + font-size: 80%; + } + h0.minitoc { + margin-left: 0em; + font-size: 90%; + } + h0.c, h1.c, h2.c, h3.c, h4.c, h5.c, h6.c, h7.c, p.c { + text-align: center + } + h1.red, h2.red, h3.red, h4.red, h5.red, h6.red, h7.red { + text-align: center; + color: #ff0000; + margin-left: 5mm; + text-indent: 5mm; + margin-top: 30px; + margin-bottom: 20px; + margin-right: 15mm; + } + h1.ruby, h2.ruby, h3.ruby, h4.ruby, h5.ruby, h6.ruby, h7.ruby { + text-align: center; + color: #990000; + margin-left: 5mm; + text-indent: 5mm; + margin-top: 30px; + margin-bottom: 20px; + margin-right: 15mm; + } diff --git a/markup/pod-samples/pod/live-manual/media/text/_sisu/home/index.html b/markup/pod-samples/pod/live-manual/media/text/_sisu/home/index.html new file mode 100644 index 0000000..c0702e7 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/_sisu/home/index.html @@ -0,0 +1,58 @@ +<html> + +<head> + <title>Live Systems Project</title> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8" /> +</head> + +<body> + <h2>Live Systems Manual</h2> + + <h3>Available Languages</h3> + + <ul> + <li><a href="index.ca.html">Català (Catalan)</a></li> + <li><a href="index.de.html">Deutsch (German)</a></li> + <li><a href="index.en.html">English</a></li> + <li><a href="index.es.html">Español (Spanish)</a></li> + <li><a href="index.fr.html">Français (French)</a></li> + <li><a href="index.it.html">Italiano (Italian)</a></li> + <li><a href="index.ja.html">日本語 (Japanese)</a></li> + <li><a href="index.pl.html">Polski (Polish)</a></li> + <li><a href="index.pt_BR.html">Português Brasil (Brazilian Portuguese)</a></li> + <li><a href="index.ro.html">Româna (Romanian)</a></li> + </ul> + + <h3>Search</h3> + +<td align="center" bgcolor="#ffffff"> +<a name="search"></a> +<form method="get" action="http://live.debian.net/manual/git/search.cgi" target="_top"> +<font size="2"> +<input type="text" name="s1" size="24" maxlength="255" /> +<input type="hidden" name="db" value="SiSUv6c_manual" /> +<input type="hidden" name="ltd" value="1000" /> +<input type="hidden" name="off" value="0" /> +<input type="hidden" name="doc" value="live-manual" /><br /> +<input type="submit" name="search" value="search db" /> +<input type="submit" name="search" value="search text" /> +</font></form> +</td> + + <h3>Meta</h3> + + <p> + Builds are scheduled @INTERVAL@. + </p> + + <ul> + <li><a href="log">log</a></li> + <li><a href="trace">trace</a></li> + </ul> + + <p> + <a href="http://live-systems.org/">Live Systems Project</a> <<a href="mailto:debian-live@lists.debian.org">debian-live@lists.debian.org</a>> - <a href="http://live-systems.org/project/legal/">Legal Information</a> + </p> +</body> + +</html> diff --git a/markup/pod-samples/pod/live-manual/media/text/_sisu/image/.empty b/markup/pod-samples/pod/live-manual/media/text/_sisu/image/.empty new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/_sisu/image/.empty diff --git a/markup/pod-samples/pod/live-manual/media/text/_sisu/sisurc.yml b/markup/pod-samples/pod/live-manual/media/text/_sisu/sisurc.yml new file mode 100644 index 0000000..7583a21 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/_sisu/sisurc.yml @@ -0,0 +1,74 @@ +# Name: SiSU - Simple information Structuring Universe +# Author: ralph@amissah.com +# Description: Site wide environment defaults set here +# system environment info / resource configuration file, for sisu +# License: GPL v3 or later +# site environment configuration file +# this file should be configured and live in +# /etc/sisu #per environment settings, overridden by: +# ~/.sisu #per user settings, overridden by: +# ./_sisu #per local markup directory settings +#% #image source directory, main path and subdirectories +#image: +# path: 'sisu_working' +# public: '_sisu/image' +# #all: 'image' + +#% presentation/web directory, main path and subdirectories (most subdirectories are created automatically based on markup directory name) +webserv: + url_root: 'http://live-systems.org' #without dir stub + path: '../build' +# images: '_sisu/image' +# man: 'man' +# cgi: '/usr/lib/cgi-bin' + +show_output_on: 'filesystem_url' + +#% papersize, (LaTeX/pdf) available values: A4, US_letter, book_b5, book_a5, US_legal +default: + papersize: 'a4,letter' + +#% output_dir_structure_by: language (language_and_filetype); filetype; or filename (original v1 & v2) +output_dir_structure_by: filetype +#% lingual: 'multi' | 'mono' (multi default) +#lingual: mono + +permission_set: + zap: true + css_modify: true +# remote_base_site: true + +program_set: + rmagick: false +# wc: true +# editor: true +# postgresql: true +# sqlite: true +# tidy: true +# rexml: true +# pdflatex: true + +#program_select: +# editor: 'vim' +# pdf_viewer: 'evince' +# web_browser: 'iceweasel' +# console_web_browser: 'links2' #'elinks' #'w3m' #'lynx' #'links' +# odf_viewer: 'lowriter' #'oowriter' #'abiword' +# xml_viewer: 'xml-viewer' +# epub_viewer: 'ebook-viewer' #'calibre' #'fbreader' #'okular' +# info_viewer: 'pinfo -f' +# man: 'man' #'groff -man -Tascii' # 'nroff -man' + +#% search form +search: + sisu: + flag: true + action: http://live-systems.org/manual/git/search.cgi + db: manual + title: Live Manual Search Form + +omit: + links_to_manifest: true +# html_navigation: true + +#omit_list: html_navigation manifest_links diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/about_manual.ssi new file mode 100644 index 0000000..00f39a0 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/about_manual.ssi @@ -0,0 +1,284 @@ +:B~ Sobre aquest manual + +1~about-manual Sobre aquest manual + +Aquest manual serveix com a punt d'accés únic a tota la documentació +relacionada amb el ${project} i en particular s'aplica al programari produït +pel projecte per a la versió Debian 9.0 "${stable}". Una versió actualitzada +es pot trobar sempre a http://live-systems.org/ + +Si bé live-manual es centra principalment en ajudar a construir un sistema +viu i no en temes dels usuaris finals, un usuari final pot trobar informació +útil en aquestes seccions: {Conceptes bàsics}#the-basics abasta la +descàrrega d'imatges prefabricades i la preparació de les imatges per a ser +arrencades des dels dispositius o la xarxa, ja sigui utilitzant el servei de +construcció d'imatges web o executant live-build directament en el +sistema. {Personalització dels comportaments en temps +d'execució}#customizing-run-time-behaviours descriu algunes de les opcions +que es poden especificar durant l'arrencada del sistema, com ara la selecció +de la disposició del teclat, la configuració regional i l'ús de la +persistència. + +Algunes de les ordres esmentades en el text s'han d'executar amb privilegis +de superusuari que es poden obtenir esdevenint l'usuari root amb #{su}# o +mitjançant l'ús de #{sudo}#. Per a distingir entre les ordres que poden ser +executades per un usuari sense privilegis i aquelles que requereixen +privilegis de superusuari, s'anteposa #{$}# o #{#}# respectivament. Aquest +símbol no és part de l'ordre. + +2~ Per als impacients + +Si bé creiem que tot el que hi ha en aquest manual és important, si més no, +per a alguns dels nostres usuaris, ens adonem que hi ha una gran quantitat +de material per a cobrir i que és possible que es vulgui experimentar l'èxit +amb el programari aviat, abans d'aprofundir en els detalls. Per tant, us +recomanem llegir en el següent ordre. + +En primer lloc, llegir aquest capítol, {Sobre aquest manual}#about-manual, +des del principi i acabant amb els {Termes}#terms. A continuació, saltar als +tres tutorials abans dels {Exemples}#examples, secció pensada per a ensenyar +com fer la construcció d'una imatge i alguns aspectes bàsics de la +personalització. Llegir en primer lloc {Ús dels exemples}#using-the-examples +seguit pel {Tutorial 1: Una imatge per defecte}#tutorial-1, {Tutorial 2: Una +utilitat de navegador web}#tutorial-2 i finalment, {Tutorial 3: Una image +personalitzada}#tutorial-3. Al final d'aquests tutorials, es tindrà una idea +del que es pot fer amb els sistemes en viu. + +Us animem a tornar i a fer un estudi del manual en profunditat, la propera +lectura pot ser {Conceptes bàsics}#the-basics, fregant o saltant {Construir +una imatge netboot}#building-netboot-image, i acabant amb la lectura de la +{Visió general de la personalització}#customization-overview i els capítols +que segueixen. En aquest punt, esperem que estigueu ben emocionats pel que +es pot fer amb els sistemes en viu i motivats per llegir la resta del +manual, de principi a fi. + +2~terms Termes + +_* *{Sistema viu}*: Un sistema operatiu que pot arrencar sense necessitat +d'instal·lació en un disc dur. Els sistemes vius no alteren el sistema +operatiu local(s) o els fitxer(s) ja instal·lats al disc dur de l'ordinador +a menys que així se'ls ho indiqui. Els sistemes vius normalment s'inician +des de dispositius, com ara CDs, DVDs o memòries USB. Alguns també poden +arrencar des de la xarxa (amb les imatges netboot, veure {Construir una +imatge netboot}#building-netboot-image), o mitjançant internet (amb el +parametre #{fetch=URL}#, veure {Webbooting}#webbooting). + +_* *{Medi en viu}*: A diferència de sistema en viu, el medi en viu es +refereix al CD, DVD o memòria USB on es copia el fitxer binari produït per +live-build i utilitzat per a arrencar el sistema en viu. Més àmpliament, el +terme també es refereix a qualsevol lloc on resideix el fitxer binari als +efectes d'iniciar el sistema en viu, com ara la ubicació dels fitxers per a +arrencar en xarxa. + +_* *{${project}}*: El projecte que manté, entre altres, els paquets +live-boot, live-build, live-config, live-tools i live-manual. + +_* *{Sistema amfitrió}*: L'entorn utilitzat per a crear el sistema en viu. + +_* *{Sistema objectiu}*: L'entorn que s'utilitza per a executar el sistema +en viu. + +_* *{live-boot}*: Una col·lecció de scripts per a arrencar els sistemes +vius. + +_* *{live-build}*: Una col·lecció d'scripts utilitzats per a construir +sistemes en viu personalitzats. + +_* *{live-config}*: Una col·lecció de scripts utilitzats per a configurar un +sistema en viu durant el procés d'arrencada. + +_* *{live-tools}*: Una col·lecció d'scripts addicionals que s'utilitzen per +a realitzar tasques útils en un sistema viu en execució. + +_* *{live-manual}*: Aquest document és mantingut en un paquet anomenat +live-manual + +_* *{Instal·lador de Debian (d-i)}*: El sistema oficial d'instal·lació de la +distribució Debian. + +_* *{Paràmeters d'arrencada}*: Els paràmetres que es poden introduir a +l'indicador del carregador d'arrencada per a influir en el nucli o +live-config + +_* *{chroot}*: El programa /{chroot}/, #{chroot(8)}#, ens permet executar +diferentes instàncies d'un entorn GNU/Linux a la vegada en un sol sistema +sense reiniciar. + +_* *{Imatge binaria}*: Un fitxer que conté el sistema en viu, com ara +live-image-i386.hybrid.iso o live-image-i386.img. + +_* *{Distribució objectiu}*: La distribució en què es basa el sistema en +viu. Que pot diferir de la distribució del sistema amfitrió. + +_* *{stable/testing/unstable}*: La distribució *{stable}*, actualment +anomenada ${stable}, conté l'última distribució de Debian llençada +oficialment. La distribució *{testing}*, temporalment anomenada ${testing}, +és l'àrea d'assaig per a la pròxima versió *{stable}*. Un avantatge +important de l'ús d'aquesta distribució és que té versions més recents del +programari en relació amb l'edició *{stable}*. La distribució *{unstable}*, +permanentment anomenada sid, és on es produeix el desenvolupament actiu de +Debian. En general, aquesta distribució és utilitzada pels desenvolupadors i +els que els agrada viure en risc. Al llarg del manual, es tendeix a +utilitzar els seus noms en clau, com ara ${testing} o sid, ja que és el que +fan servir les pròpies eines. + +2~ Autors + +Llistat d'autors (en ordre alfabètic) + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contribuir a aquest document + +Aquest manual està pensat com un projecte comunitari i totes les propostes +per a millorar-lo i les contribucions són molt benvingudes. Veure la secció +{Contribuir al projecte}#contributing-to-project per a obtenir informació +detallada sobre com obtenir la clau i fer bons commits. + +3~applying-changes Aplicar canvis + +Per tal de realitzar canvis en el manual anglès s'ha d'editar els fitxers +adequats a #{manual/en/}# però abans de presentar una contribució, s'ha de +previsualitzar el treball. Per a previsualitzar el live-manual, assegurar-se +que s'han instal·lat els paquets necessaris per a la seva construcció +mitjançant l'execució de: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Es pot crear el live-manual des del directori de nivell superior del arbre +Git mitjançant l'execució de: + +code{ + + $ make build + +}code + +Tenint en compte que es necessita un cert temps per construir el manual en +tots els idiomes suportats, els autors poden utilitzar un dels mètodes +abreujats per fer revisions ràpides de la nova documentació que han afegit +al manual en anglès. Amb #{PROOF=1}# es construeix live-manual en format +html, però sense els fitxers html segmentats, i amb #{PROOF=2}# es +construeix live-manual en format pdf, però només el retrat A4 i carta. És +per això que amb l'ús de qualsevol de les possibilitats #{PROOF=}# es pot +estalviar una quantitat considerable de temps, per exemple: + +code{ + + $ make build PROOF=1 + +}code + +Quan es revisa una de les traduccions, és possible construir un sol idioma +mitjançant l'execució de, per exemple: + +code{ + + $ make build LANGUAGES=de + +}code + +També es possible crear per tipus de document, per exemple: + +code{ + + $ make build FORMATS=pdf + +}code + +O combinar tot dos, per exemple: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +Després de revisar el treball i assegurar-se que tot està bé, no fer un +#{make commit}# a menys que s'actualitzin les traduccions al mateix temps, i +en aquest cas, no barrejar els canvis al manual anglès i les traduccions en +el mateix commit, fer-ne un altre separat per a cada canvi. Veure la secció +{Traducció}#translation per a més detalls. + +3~translation Traducció + +Per a traduir live-manual, seguir aquests passos, depenent de si s'està +començant una traducció des de zero o si es segueix treballant en una ja +existent: + +_* Començar una nova traducció des de zero + +_2* Traduir els fitxers *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* +i *{index.html.in.pot}* de #{manual/pot/}# a la vostra llengua amb el vostre +editor favorit (per exemple /{poedit}/). Enviar els fitxers #{.po}# traduïts +a la llista de correu per comprovar la seva integritat. La comprovació +d'integritat de live-manual garanteix que els fitxers #{.po}# són traduïts +al 100% però també detecta possibles errors. + +_2* Un cop comprovats, per a activar una nova llengua al autobuild, només +cal afegir els fitxers inicials traduïts a #{manual/po/${LANGUAGE}/}# i +executar #{make commit}#. I llavors editar #{manual/_sisu/home/index.html}# +afegint el nom de la llengua i el seu nom en anglès entre parèntesis. + +_* Continuar amb una traducció ja començada + +_2* Una vegada que s'ha afegit la nova llengua, es pot continuar traduint la +resta de fitxers .po dins de #{manual/po/${LANGUAGE}/}# a l'atzar amb +l'editor favorit (com per exemple /{poedit}/). + +_2* No oblidar que es necessari fer un #{make commit}# per a garantir que +els manuals traduïts s'actualitzin a partir dels fitxers .po i llavors es +poden revisar els canvis executant #{make build}# abans de #{git add .}#, +#{git commit -m "Translating..."}# i #{git push}#. Recordar que #{make +build}# pot trigar una quantitat considerable de temps, però es poden +revisar els idiomes de forma individual com s'explica a la secció {Aplicar +canvis}#applying-changes + +Després d'executar #{make commit}# es podrà veure bastant text a la +pantalla. Bàsicament són missatges informatius sobre l'estat del procés i +també algunes pistes sobre el que es pot fer per a millorar live-manual. Si +no es veu cap error fatal, generalment es pot procedir i enviar la +contribució. + +live-manual ve amb dues utilitats que poden ser de gran ajuda pels +traductors a l'hora de trobar missatges sense traduir i difusos. La primera +és "make translate". Aquesta activa un script que diu en detall quants +missatges sense traduir hi ha a cada fitxer .po. La segona, "make fixfuzzy", +només actua sobre els missatges difusos però ajuda a trobar-los i +corregir-los un per un. + +Tenir en compte que tot i que aquestes utilitats poden ser molt útils per a +fer traduccions en la línia d'ordres, l'ús d'una eina especialitzada com +/{poedit}/ és la manera recomanada de fer la tasca. També és una bona idea +llegir la documentació de localització de debian (l10n) i, específicament +dins live-manual, les {Directrius per a traductors}#guidelines-translators. + +*{Nota:}* Es pot utilitzar #{make clean}# per a netejar l'arbre git abans de fer un push. Aquest pas no és obligatori, gràcies al fitxer .gitignore, però és una bona pràctica per a evitar enviar fitxers de forma involuntària. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/about_project.ssi new file mode 100644 index 0000000..f2d48a4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/about_project.ssi @@ -0,0 +1,106 @@ +:B~ Sobre el ${project} + +1~about-project Sobre el ${project} + +2~ Motivació + +3~ Què passa amb els sistemes vius actuals + +Quan el ${project} va començar, ja hi havia diversos sistemes vius basats en +Debian disponibles i que estaven fent una gran feina. Des de la perspectiva +de Debian la majoria d'ells tenien un o més dels desavantatges següents: + +_* No són projectes de Debian i per tant no tenen suport des de Debian. + +_* Es barregen diferents distribucions, per exemple *{testing}* i +*{unstable}*. + +_* Només donen suport a i386. + +_* Es modifique el comportament i/o l'aparença dels paquets, per a estalviar +espai. + +_* S'inclouen paquets de fora de l'arxiu de Debian. + +_* Inclouen nuclis personalitzats amb pedaços addicionals que no són part de +Debian. + +_* Són grans i lents a causa de la seva mida i per tant no aptes com a +sistemes de rescat. + +_* No estan disponibles en diferents formats, per exemple, CD, DVD, memòries +USB i imatges netboot. + +3~ Per què crear el nostre pròpi sistema viu? + +Debian és el sistema operatiu universal: Debian té un sistema viu per a +mostrar arreu i per a representar acuradament el sistema Debian amb els +següents avantatges: + +_* Es tracta d'un subprojecte de Debian. + +_* Reflecteix l'estat (actual) d'una distribució. + +_* Funciona en tantes arquitectures com és possible. + +_* Es tracta només de paquets Debian sense modificacions. + +_* No conté paquets que no són a l'arxiu de Debian. + +_* S'utilitza un nucli Debian sense alteracions i sense pedaços addicionals. + +2~ Filosofia + +3~ Només paquets Debian sense modificacions de la secció "main" + +Només farem servir els paquets del repositori de Debian de la secció +"main". La secció non-free no és part de Debian i per tant no es pot +utilitzar per a les imatges oficials del sistema viu. + +No canviarem cap paquet. Cada vegada que hàgim de canviar alguna cosa, ho +farem en coordinació amb el mantenidor del paquet a Debian. + +Com a excepció, els nostres propis paquets, com ara live-boot, live-build o +live-config poden ser utilitzats temporalment des del nostre propi +repositori per raons de desenvolupament (per exemple, per a crear +instantànies de desenvolupament). Aquests paquets es pujaran a Debian de +forma regular. + +3~ Paquets del sistema viu sense cap configuració + +En aquesta fase no es publicarà o s'instal·larà cap configuració alternativa +o d'exemple. Tots els paquets són utilitzats en la seva configuració per +defecte, tal com són després d'una instal·lació normal de Debian. + +Cada vegada que ens calgui una configuració per defecte diferent, ho farem +en coordinació amb el mantenidor del paquet Debian. + +S'hi inclou un sistema per a configurar paquets mitjançant debconf que +permet instal·lar paquets configurats de forma personalitzada dins d'una +imatge en viu, però per a les {imatges en viu +prefabricades}#downloading-prebuilt-images només utilitzarem una +configuració per defecte, a menys que sigui absolutament necessari per a +poder treballar en l'entorn en viu. Sempre que sigui possible, preferim +adaptar els paquets a l'arxiu de Debian perquè funcionin en un sistema en +viu abans que realitzar canvis en la cadena d'eines en viu o en {les +configuracions de les imatges +prefabricades}#clone-configuration-via-git. per a obtenir més informació, +veure {Visió general de la personalització}#customization-overview. + +2~contact Contacte + +_* *{Llista de correu}*: El contacte principal del projecte és la llista de +correu a https://lists.debian.org/debian-live/. Es pot enviar un correu +directament a debian-live@lists.debian.org Els arxius de la llista són a +https://lists.debian.org/debian-live/. + +_* *{IRC}*: Un nombre d'usuaris i desenvolupadors estan presents al canal +#debian-live a irc.debian.org (OFTC). Quan es pregunta al IRC, s'ha de tenir +paciència esperant una resposta, si no hi ha cap resposta, es pot enviar un +correu a la llista. + +_* *{BTS}*: El{Sistema de seguiment d'errors de +Debian}https://www.debian.org/Bugs/ (BTS) conté detalls d'errors notificats +per usuaris i desenvolupadors. A cada error se li assigna un número i es +manté a l'arxiu fins que es marca com tractat. Per a obtenir més informació, +vegeu {Informar dels errors}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/appendix_style-guide.ssi new file mode 100644 index 0000000..5a2652a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/appendix_style-guide.ssi @@ -0,0 +1,376 @@ +:B~ Style guide + +1~style-guide Guia d'estil + +2~ Instruccions per als autors + +Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte +al escriure documentació tècnica per a live-manual. Es divideixen en +aspectes lingüístics i procediments recomanats. + +*{Nota:}* Els autors han de llegir primer {Contribuir a aquest document}#how-to-contribute + +3~ Característiques lingüístiques + +_* /{Utilitzar un anglès planer}/ + +Tenir en compte que un alt percentatge dels lectors no són parlants nadius +d'anglès. Així que, com a regla general, intentar utilitzar frases curtes i +significatives, seguides d'un punt i apart. + +Això no vol dir que s'hagi d'utilitzar un estil simplista i ingenu. És un +suggeriment per intentar evitar, en la mesura del possible, les oracions +subordinades complexes que fan que el text sigui difícil d'entendre per als +parlants no nadius d'anglès. + +_* /{Varietat d'anglès}/ + +Les varietats d'anglès més esteses són el britànic i l'americà, així que és +molt probable que la majoria dels autors acabin utilitzant l'una o +l'altra. En un entorn de col·laboració, la varietat ideal seria "l'anglès +internacional", però és molt difícil, per no dir impossible, decidir quina +varietat d'entre totes les existents, és la millor. + +Esperem que les diferents varietats es puguin barrejar sense crear +malentesos, però en termes generals s'ha d'intentar ser coherent i abans de +decidir sobre l'ús de l'anglès britànic, l'anglès americà o qualsevol altra +varietat, fer una ullada a com escriuen altres persones i tractar d'imitar +l'estil. + +_* /{Ser equilibrat}/ + +S'ha de ser imparcial. Evitar incloure referències a ideologies totalment +alienes a live-manual. L'escriptura tècnica ha de ser el més neutral +possible. Està en la naturalesa mateixa de l'escriptura científica. + +_* /{Ser políticament correcte}/ + +Evitar el llenguatge sexista tant com sigui possible. Si es necessita fer +referència a la tercera persona del singular utilitzar preferiblement "they" +en lloc de "he" or "she" o invents estranys com per exemple "s/he" o +"s(he)". + +_* /{Ser concís}/ + +Anar directament al gra i no fent voltes. Donar tota la informació +necessària, però no afegir més informació de la necessària, és a dir, no +explicar detalls innecessaris. Els lectors són intel·ligents. Es presumeix +algun coneixement previ per la seva part. + +_* /{Minimitzar la feina de traducció}/ + +Tenir en compte que qualsevol cosa que s'escrigui haurà de ser traduida a +diverses llengües. Això implica que un nombre de persones hauran de fer un +treball extra si s'agrega informació innecessària o redundant. + +_* /{Ser coherent}/ + +Com s'ha suggerit abans, és gairebé impossible estandarditzar un document +escrit en col·laboració en un tot perfectament unificat. No obstant això, +s'aprecia tot esforç per escriure d'una manera coherent amb la resta dels +autors. + +_* /{Cohesió}/ + +Utilitzar connectors del discurs perquè el text sigui coherent i sense +ambigüitats. (Normalment s'anomenen connectors). + +_* /{Ser descriptiu}/ + +És preferible descriure l'assumpte en un o diversos paràgrafs en lloc +d'utilitzar una sèrie de oracions en un típic estil de "changelog". Cal +descriure-ho! Els Lectors ho agrairan. + +_* /{Diccionari}/ + +Buscar el significat de les paraules en un diccionari o una enciclopèdia si +no es sap com expressar certs conceptes en anglès. Però cal tenir en compte +que un diccionari pot ser el millor amic o pot convertir-se en el pitjor +enemic si no es sap com utilitzar-lo correctament. + +L'anglès té el vocabulari més gran que existeix (amb més d'un milió de +paraules). Moltes d'aquestes paraules són préstecs d'altres llengües. Al +buscar el significat de les paraules en un diccionari bilingüe la tendència +d'un parlant no nadiu d'anglès és triar la que sona més semblant en la seva +llengua materna. Sovint, això es converteix en un discurs excessivament +formal que no sona ben natural en anglès. + +Com a regla general, si un concepte es pot expressar utilitzant diferents +sinònims, és un bon consell triar la primera paraula proposada pel +diccionari. En cas de dubte, és sovint correcte elegir les paraules d'origen +germànic (Normalment paraules monosíl·labes). Tenir en compte que aquestes +dues tècniques poden produir un discurs més aviat informal, però almenys la +elecció de paraules serà d'ampli ús i acceptació general. + +L'ús d'un diccionari de frases fetes es recomanable. Són molt útils quan es +tracta de saber quines paraules solen aparèixer juntes. + +Com s'ha dit abans, és una bona pràctica aprendre del treball dels +altres. L'ús d'un motor de recerca per comprovar com altres autors utilitzen +certes expressions pot ajudar molt. + +_* /{Falsos amics, modismes i altres expressions idiomàtiques}/ + +Compte amb els falsos amics. No importa com de competent un és en un idioma +estranger, de tant en tant es pot caure en el parany dels anomenats "falsos +amics", paraules que s'assemblen en dos idiomes però els significats o usos +poden ser completament diferents. + +Intentar evitar els modismes tant com sigui possible. Els "modismes " són +expressions que tenen un significat completament diferent del que les seves +paraules per separat semblen voler dir. De vegades, els modismes poden ser +difícils d'entendre fins i tot per als parlants nadius d'anglès! + +_* /{Evitar l'argot, les abreviatures, les contraccions...}/ + +Tot i que s'anima a utilitzar un anglès senzill i planer, l'escriptura +tècnica pertany al registre formal de la llengua. + +Intentar evitar l'argot, les abreviatures inusuals que són difícils +d'entendre i per sobre de tot, les contraccions que tracten d'imitar el +llenguatge parlat. Per no parlar d'expressions familiars o típiques de +l'irc. + +3~ Procediments + +_* /{Provar abans d'escriure}/ + +És important que els autors provin els seus exemples abans d'afegir-los a +live-manual per assegurar-se que tot funciona com es descriu. Fer les proves +en un entorn chroot net o en una màquina virtual pot ser un bon punt de +partida. A més, seria ideal si les proves fossin dutes a terme en diferents +ordinadors amb un maquinari diferent per detectar els possibles problemes +que puguin sorgir. + +_* /{Exemples}/ + +Quan es posa un exemple mirar de ser el més específic possible. Un exemple +és, després de tot, només un exemple. + +Sovint és millor utilitzar una línia que només s'aplica a un cas concret que +l'ús d'abstraccions que poden confondre als lectors. En aquest cas es pot +donar una breu explicació dels efectes de l'exemple proposat. + +Hi pot haver algunes excepcions quan l'exemple suggereixi l'ús d'algunes +ordres potencialment perilloses que, si s'utilitzen incorrectament, poden +provocar la pèrdua de dades o altres efectes indesitjables similars. En +aquest cas, s'haurà de proporcionar una explicació detallada sobre els +possibles efectes secundaris. + +_* /{Enllaços externs}/ + +Els enllaços a llocs externs només s'han d'utilitzar quan la informació en +aquests llocs és crucial per a comprendre un punt especial. Tot i això, +intentar utilitzar els enllaços a llocs externs el menys possible. Els +enllaços d'internet poden canviar de tant en tant, donant lloc a enllaços +trencats i deixant els arguments en un estat incomplet. + +A més, la gent que llegeix el manual sense connexió no podrà seguir els +enllaços. + +_* /{Evitar les marques i les coses que violen la llicència sota la qual es +publica el manual}/ + +Intentar evitar les marques tant com sigui possible. Tenir en compte que +altres projectes derivats poden fer ús de la documentació que escrivim. Així +que estem complicant les coses per a ells si s'afegix determinat material +específic. + +live-manual es publica sota la llicència GNU GPL. Això té una sèrie +d'implicacions que s'apliquen a la distribució dels materials (de qualsevol +tipus, incloent-hi gràfics o logotips amb drets d'autor) que es publica amb +ell. + +_* /{Escriure un primer esborrany, revisar, editar, millorar, fer de nou si +és necessari}/ + + - Pluja d'idees!. Es necessari organitzar les idees primer en una seqüència + lògica d'esdeveniments. + + - Quan d'alguna manera ja s'han organitzat aquestes idees en la ment, + escriure un primer esborrany. + + - Revisar la gramàtica, la sintaxi i l'ortografia. Tenir en compte que els + noms propis de les versions, com ara ${testing} o sid, no s'han + d'escriure en majúscula quan es refereixen als noms en clau. Per tal de + comprovar l'ortografia es pot executar el target "spell". És a dir, + #{make spell}# + + - Millorar les frases i refer qualsevol part si és necessari. + +_* /{Capítols}/ + +Utilitzar el sistema de numeració convencional dels capítols i +subtítols. Per exemple 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 +... i així successivament. Veure marcat a continuació. + +Si s'ha d'enumerar una sèrie de passos o etapes en la descripció, també es +poden utilitzar els nombres ordinals: primer, segon, tercer ... o en primer +lloc, llavors, després, per fi ... Alternativament, es poden utilitzar +punts. + +_* /{Marcat}/ + +I per últim però no menys important, live-manual utilitza +{SiSU}http://www.sisudoc.org/ per processar els fitxers de text i produir +múltiples formats. Es recomana fer una ullada al {manual de +SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html per a +familiaritzar-se amb el seu marcat, o bé escriure: + +code{ + + $ sisu --help markup + +}code + +Aquests són alguns exemples de marcat que poden ser útils: + + - Per a l'èmfasi/negreta: + +code{ + +*{foo}* o !{foo}! + +}code + +produeixen: *{foo}* o !{foo}!. S'usen per emfatitzar certes paraules clau. + + - Per a la cursiva: + +code{ + +/{foo}/ + +}code + +produeix: /{foo}/. S'usa, per exemple, per als noms dels paquets Debian. + + - Per a monospace: + +code{ + +#{foo}# + +}code + +produeix: #{foo}#. S'usa per exemple, per als noms de les ordres. I també +per ressaltar algunes paraules clau o coses com les rutes. + + - Per a blocs de codi: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produeix: + +code{ + + $ foo + # bar + +}code + +S'utilitza #{code{}# per a obrir i #{}code}# per a tancar els blocs. És +important recordar deixar un espai al principi de cada línia de codi. + +2~guidelines-translators Directrius per als traductors + +Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte a +l'hora de traduir el contingut de live-manual. + +Com a recomanació general, els traductors haurien d'haver llegit i entès les +regles de traducció que s'apliquen als seus llenguatges específics. En +general, els grups de traductors i les llistes de correu proporcionen +informació sobre com produir traduccions que compleixin amb els estàndards +de qualitat de Debian. + +*{Nota:}* Els traductors també han de llegir {Contribuir a aquest document}#how-to-contribute. En particular, la secció {Traducció}#translation + +3~ Consells de traducció + +_* /{Comentaris}/ + +El paper del traductor és transmetre el més fidelment possible el significat +de les paraules, oracions, paràgrafs i textos de com van ser escrits pels +autors originals al seu idioma. + +Per tant, aquests, s'han d'abstenir d'afegir comentaris personals o +informacions addicionals pel seu compte. Si es vol afegir un comentari per +als traductors que treballen en els mateixos documents, es poden deixar a +l'espai reservat per a això. És a dir, la capçalera de les cadenes dels +fitxers *{po}* precedits pel signe *{#}*. La majoria dels programes gràfics +de traducció poden manejar aquest tipus de comentaris automàticament. + +_* /{NT, Nota del Traductor}/ + +És perfectament acceptable però, incloure una paraula o una expressió entre +parèntesi en el text traduït si, i només si, aixó fa que el significat d'una +paraula o expressió difícil sigui més clara per al lector. Dins dels +parèntesis, el traductor ha de posar de manifest que l'addició és seva +utilitzant l'abreviatura "NT" o "Nota del traductor". + +_* /{Frases impersonals}/ + +Els documents escrits en anglès fan un gran ús de la forma impersonal +"you". En alguns altres idiomes que no comparteixen aquesta característica, +això pot donar la falsa impressió que els textos originals s'adresen +directament el lector quan en realitat n'ho fan. Els traductors han de ser +conscients d'aquest fet i ho han de reflectir en el seu idioma amb la major +precisió possible. + +_* /{Falsos amics}/ + +El perill dels "falsos amics" explicat anteriorment s'aplica especialment +als traductors. Tornar a comprovar el significat dels falsos amics +sospitosos en cas de dubte. + +_* /{Marcat}/ + +Els traductors que treballin inicialment amb els fitxers *{pot}* i +posteriorment amb els fitxers *{po}* trobaràn moltes característiques de +marcat en les cadenes. Es pot traduir el text, sempre que sigui traduïble, +però és extremadament important que s'utilitzi exactament el mateix marcat +que a la versió original en anglès. + +_* /{Blocs de codi}/ + +Tot i que els blocs de codi són generalment intraduïbles, incloure'ls en la +traducció és l'única manera de conseguir una traducció completa al 100%. I +encara que això signifiqui més feina al principi, ja que pot requerir la +intervenció dels traductors s'hi ha canvis en el codi, és la millor manera, +a la llarga, per identificar el que s'ha traduït i el que no al comprovar la +integritat dels fitxers .po. + +_* /{Salts de línia}/ + +Els texts traduïts han de tenir exactament els mateixos salts de línia que +els texts originals. Aneu amb compte de pressionar la tecla "Enter" o +escriure *{\n}* si apareix als fitxers originals. Aquests salts de línies +apareixen sovint, per exemple, en els blocs de codi. + +No confondre's, això no vol dir que el text traduït hagi de tenir la mateixa +longitud que la versió en anglès. Aixó és gairebé impossible. + +_* /{Cadenes intraduïbles}/ + +Els traductors no han de traduir mai: + + - Els noms en clau de les versions (que han de ser escrits en minúscules) + + - Els noms dels programes + + - Les ordres que es posen com a exemples + + - Les metadades (apareixen sovint entre dos punts *{:metadata:}*) + + - Els enllaços + + - Les rutes diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/examples.ssi new file mode 100644 index 0000000..1aa1220 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/examples.ssi @@ -0,0 +1,454 @@ +:B~ Exemples + +1~examples Exemples + +En aquest capítol s'inclouen exemples de construccions per a casos d'ús +específics amb sistemes en viu. Si s'és nou en la construcció d'imatges en +viu pròpies, us suggerim mirar els tres tutorials en seqüència, ja que cada +un ensenya noves tècniques que ajuden a utilitzar i entendre els exemples +restants. + +2~using-the-examples Ús dels exemples + +per a utilitzar aquests exemples es necessita un sistema de construcció que +compleixi les exigències enumerades a {Requisits}#requirements y que tingui +live-build instal·lat com es descriu a {Instal·lació de +live-build}#installing-live-build. + +Cal notar que, per a abreujar, en aquests exemples no s'especifica un mirall +local per a utilitzar en la construcció. Es poden accelerar les descàrregues +considerablement si s'utilitza un mirall local. Es pot especificar les +opcions quan s'utilitza #{lb config}#, com es descriu a {Miralls de +distribució utilitzats en temps de +construcció}#distribution-mirrors-build-time, o per a major comoditat, +establir el valor predeterminat per al sistema de construcció en el fitxer +#{/etc/live/build.conf}#. Només cal crear aquest fitxer i establir a les +variables al mirall preferit. Tots els altres miralls que s'utilitzin en la +construcció adoptaran valors per defecte segons aquests valors. Per exemple: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-updates/" + +}code + +2~tutorial-1 Tutorial 1: Una imatge per defecte + +*{Cas d'ús:}* Crear una primera imatge senzilla, aprenent els conceptes bàsics de live-build. + +En aquest tutorial, anem a construir una imatge ISO híbrida per defecte que +contingui només els paquets de base (no té Xorg) i altres paquets de suport +de sistema en viu, com un primer exercici en l'ús de live-build. + +No pot ser més senzill que això: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examinar el contingut del directori #{config/}# si es vol. Es veurà +emmagatzemada aquí una configuració en esquelet, a punt per a ser +personalitzada o, en aquest cas, per a ser utilitzada immediatament per a +construir una imatge per defecte. + +Ara, com a superusuari, construir la imatge, guardant un log del que es +construeix amb #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Suposant que tot va bé, després d'una estona, el directori actual contindrà +una #{live-image-i386.hybrid.iso}#. Aquesta imatge ISO híbrida es pot +arrencar en una màquina virtual tal com s'explica a {Provar una imatge ISO +amb Qemu}#testing-iso-with-qemu i {Provar una imatge ISO amb +VirtualBox}#testing-iso-with-virtualbox, o bé copiada a un dispositiu USB +com es descriu a {Gravar una imatge ISO en un medi físic}#burning-iso-image +i {Copiar una imatge ISO híbrida en un dispositiu +USB}#copying-iso-hybrid-to-usb, respectivament. + +2~tutorial-2 Tutorial 2: Una utilitat de navegador web + +*{Cas d'ús:}* Crear una imatge d'una utilitat de navegador web, aprenent a aplicar personalitzacions. + +En aquest tutorial, anem a crear una imatge adequada per al seu ús com a una +utilitat de navegador web, que serveix com introducció a la personalització +de les imatges de sistemes en viu. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +La nostra elecció de LXDE per a aquest exemple reflecteix el nostre desig +d'oferir un entorn d'escriptori mínim, ja que l'objectiu de la imatge és +l'únic ús que tenim al cap, el navegador web. Podríem anar encara més lluny +i oferir una configuració per defecte per al navegador web a +#{config/includes.chroot/etc/iceweasel/profile/}#, o paquets addicionals de +suport per a la visualització de diversos tipus de contingut web, però +deixem això com a un exercici per al lector. + +Construir la imatge, de nou com a superusuari, guardant un log com al +{Tutorial 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Un cop més, verificar que la imatge està bé i provar-la, com al {Tutorial +1}#tutorial-1. + +2~tutorial-3 Tutorial 3: Una imatge personalitzada + +*{Cas d'ús:}* Crear un projecte per a construir una imatge personalitzada, que contingui el programari favorit per a portar en una memòria USB allà on es vagi i que evolucionarà en revisions successives tal i com les necessitats i les preferències canvien. + +Com la nostra imatge personalitzada canviarà durant un nombre de revisions i +volem fer un seguiment d'aquests canvis, provar coses experimentals i +possiblement revertir-les si les coses no surten bé, anem a mantenir la +nostra configuració en el popular sistema de control de versions +#{git}#. També utilitzarem les millors pràctiques de configuració automàtica +mitjançant scripts #{auto}# com s'explica a {Gestió d'una +configuració}#managing-a-configuration. + +3~ Primera revisió + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Editar #{auto/config}# de la manera següent: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Executar #{lb config}# per a crear l'arbre de configuració, utilitzant el +script #{auto/config}# que s'acaba de crear: + +code{ + + $ lb config + +}code + +Ara, omplir la llista local de paquets: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +En primer lloc, amb #{--architectures i386}# s'assegura que al nostre +sistema de construcció #{amd64}# podem construir una versió de 32 bits +adequada per al seu ús en la majoria de màquines. En segon lloc, fem servir +#{--linux-flavours 686-pae}# perquè no creiem que utilitzarem aquesta imatge +en sistemes molt més vells. En tercer lloc, hem triat la tasca metapaquet +/{lxde}/ per a donar-nos un escriptori mínim. I, finalment, hem afegit dos +paquets inicials favorits: /{iceweasel}/ i /{xchat}/. + +Ara, construir la imatge: + +code{ + + # lb build + +}code + +Tenir en compte que a diferència dels dos primers tutorials, ja no s'ha +d'escriure #{2>&1 | tee build.log}# ja que ara s'inclou al script +#{auto/build}#. + +Quan s'ha provat la imatge (com al {Tutorial 1}#tutorial-1) i s'està +satisfet del seu funcionament, és el moment d'iniciar el repositòri #{git}#, +afegint només els scripts auto que s'han creat, i llavors fer el primer +lliurament: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Segona revisió + +En aquesta revisió, anem a netejar després de la primera construcció, afegir +el paquet /{vlc}/ a la nostra configuració, reconstruir, provar i fer el +lliurament. + +L'ordre #{lb clean}# netejarà tots els fitxers generats en la construcció +anterior a excepció del cache, el que estalvia haver de tornar a descarregar +els paquets. Això assegura que el #{lb build}# següent tornarà a executar +totes les etapes per a regenerar els fitxers de la nostra nova configuració. + +code{ + + # lb clean + +}code + +Ara afegim el paquet /{vlc}/ al llistat de paquets local a +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Construir de nou: + +code{ + +# lb build + +}code + +Provar, i quan s'estigui satisfet, fer el lliurament de la propera revisió: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Per descomptat, es possible fer canvis més complicats en la configuració, +potser afegint fitxers en els subdirectoris de #{config/}#. Quan es fa un +lliurament de les noves revisions, s'ha de tenir cura de no editar a mà o +incloure en el lliurament els fitxers de nivell superior de #{config}# que +contenen variables #{LB_*}#, ja que són productes de construcció també, i +sempre són netejats per #{lb clean}# i tornats a crear per #{lb config}# a +través dels seus respectius scripts #{auto}#. + +Hem arribat al final de la nostra sèrie de tutorials. Molts més tipus de +personalització són possibles, amb les poques característiques explorades en +aquests senzills exemples, es poden crear una varietat gairebé infinita +d'imatges diferents. Els exemples que queden d'aquesta secció tracten +diferents casos d'ús extrets de les experiències recollides dels usuaris de +sistemes en viu. + +2~ Un client per a un quiosc VNC + +*{Cas d'ús:}* Crear una imatge amb live-build per a connectar-se directament a un servidor VNC al arrencar. + +Fer un directori de treball i crear una configuració d'esquelet en el seu +interior, desactivant els «recommends» per a fer un sistema mínim. I a +continuació, crear dues llistes inicials de paquets: La primera generada per +un script proporcionat per live-build anomenat #{Packages}# (veure {Generar +llistes de paquets}#generated-package-lists), i la segona incloent-hi +/{xorg}/, /{gdm3}/, /{metacity}/ i /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +Com s'explica a {Afinar APT per a estalviar +espai}#tweaking-apt-to-save-space pot ser que s'hagi de tornar a afegir +alguns paquets recomanats per a fer que la imatge funcioni correctament. + +Una manera fàcil d'enumerar els recommends és utilitzar /{apt-cache}/. Per +exemple: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +En aquest exemple, ens vam assabentar que havíem de tornar a incloure +diversos paquets recomanats per live-config i live-boot: #{user-setup}# +perquè funcioni l'autologin i #{sudo}# com a programa essencial per a apagar +el sistema. A més, podria ser útil afegir #{live-tools}# per a poder copiar +la imatge en la memòria RAM i #{eject}# per a expulsar, finalment, el medi +en viu. Per tant: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +Després, crear el directori #{/etc/skel}# a #{config/includes.chroot}# i +posar un fitxer #{.xsession}# personalitzat per a l'usuari per defecte que +posarà en marxa /{metacity}/ i iniciarà /{xvncviewer}/, connectant al port +#{5901}# d'un servidor ubicat a #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Construir la imatge: + +code{ + + # lb build + +}code + +Gaudir-ne. + +2~ Una imatge bàsica per a un dispositiu USB de 128MB + +*{Cas d'ús:}* Crear una imatge per defecte amb alguns components eliminats per tal que càpiga en una clau USB de 128MB amb un petit espai de sobres per a utilitzar-lo com millor us sembli. + +Al optimitzar una imatge per a adaptar-la a una mida determinada, cal +comprendre la compensació que s'estan fent entre la mida i la +funcionalitat. En aquest exemple, retallem tant només per a donar cabuda a +material addicional dins d'una mida de 128MB, però sense fer res per a +destruir la integritat dels paquets continguts, com la depuració de les +dades de localització a través del paquet /{localepurge}/ o altres +optimitzacions "intrusives". De particular interès, utilitzem +#{--debootstrap-options}# per a crear un sistema mínim des de zero. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +Per a fer que la imatge funcioni correctament, hem de tornar a afegir, com a +mínim, dos paquets recomanats, que es queden fora per l'opció +#{--apt-recommends false}#. Veure { Afinar APT per a estalviar +espai}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Ara, crear la imatge de la forma habitual: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +En el sistema de l'autor en el moment d'escriure això, la configuració +anterior produeix una imatge de 110MB. Això es compara favorablement amb la +imatge de 192MB produïda per la configuració per defecte del {Tutorial +1}#tutorial-1. + +Deixar els índexs d'APT amb #{--apt-indices false}# permet estalviar una +bona quantitat d'espai, el desavantatge és que es necessita fer #{apt-get +update}# abans d'utilitzar apt en el sistema en viu. Deixar els paquets +recomanats amb #{--apt-recommends false}# estalvia una mica d'espai +addicional, a costa d'ometre alguns paquets que d'una altra manera es podria +esperar que hi fossin. #{--debootstrap-options "--variant=minbase"}# +preinstal·la un sistema mínim des del principi. Al no incloure +automàticament paquets de firmware amb #{--firmware-chroot false}# també es +guanya una mica d'espai. I finalment, #{--memtest none}# impedeix la +instal·lació d'un comprovador de memòria. + +*{Nota:}* Un sistema mínim es pot aconseguir també fent servir un script ganxo, com ara el #{stripped.hook.chroot}# de #{/usr/share/doc/live-build/examples/hooks}#. Es pot guanyar petites quantitats addicionals d'espai i produir una imatge de 91MB. No obstant, el script ganxo aconsegueix això eliminant documentació i altres fitxers dels paquets instal·lats al sistema. Això viola la integritat dels paquets i com és comenta a l'encapçalament del script, pot tenir conseqüències imprevistes. És per això que l'ús d'un /{debootstrap}/ mínim és el mètode recomanat per a aconseguir aquest objectiu. + +2~ Un escriptori GNOME localitzat i amb instal·lador + +*{Cas d'ús:}* Crear una imatge amb l'escriptori GNOME, localitzat per Suïssa i que inclogui un instal·lador. + +Volem fer una imatge ISO híbrida per a l'arquitectura i386 fent servir el +nostre escriptori preferit, en aquest cas GNOME, que conté tots els mateixos +paquets que serien instal·lats per l'instal·lador estàndard de Debian per a +GNOME. + +El nostre primer problema és descobrir els noms de les tasques del +llenguatge apropiades. En l'actualitat, live-build no ens pot ajudar amb +això. Tot i que es podria tenir sort i trobar-ho per assaig i error, hi ha +una eina, #{grep-dctrl}#, per extreure les descripcions de les tasques de +tasksel-data. Per a preparar-ho tot, assegurar-se de tenir totes dues coses: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Ara podem buscar les tasques apropiades, primer amb: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +Mitjançant aquesta ordre, es descobreix que la tasca s'anomena, amb +suficient claredat, german. Ara, per a trobar les tasques relacionades: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +En el moment d'arrencar es generarà la variant regional *{de_CH.UTF-8}* i es +seleccionarà la disposició del teclat *{ch}*. Ara posarem les peces +juntes. Recordant de {Ús dels metapaquets}#using-metapackages que els +metapaquets tenen el prefix #{task-}#, simplement especificar aquests +paràmetres del llenguatge a l'arrencada, i després afegir els paquets de +prioritat estàndard i tots els metapaquets descoberts a la nostra llista de +paquets de la següent manera: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Tenir en compte que s'ha inclòs el paquet /{debian-installer-launcher}/ per +a llançar l'instal·lador des de l'escriptori en viu. El nucli #{586}#, que +actualment és necessari perquè el llançador funcioni correctament, s'inclou +per defecte. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/ca/live-manual.ssm new file mode 100644 index 0000000..32eba0f --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manual de Live Systems" + +creator: + author: "Projecte Live Systems <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "Aquest programa és un programari lliure: es pot redistribuir i/o modificar sota els termes de la Llicència Pública General de la GNU com és publicada per la Free Software Foundation, ja sigui la versió 3 de la Llicència, o (si ho preferiu) qualsevol versió posterior. \\ \\ Aquest programa es distribueix amb l'esperança que sigui útil, però sense cap garantia, fins i tot sense la garantia implícita de COMERCIALITZACIÓ o ADEQUACIÓ PER A PROPÒSITS DETERMINATS. Vegeu la Llicència General Pública de la GNU per a més detalls. \\ \\ Haurieu de rebre una còpia de la Llicència Pública General de la GNU amb aquest programa. Si no és així, consulteu http://www.gnu.org/licenses/. \\ \\ El text complet de la Llicència Pública General de la GNU es pot trobar a /usr/share/common-licenses/GPL-3." + +date: + published: "2015-08-23" + +publisher: "Projecte Live Systems <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +#bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "`[$]{2}[{]stable[}]`,'stretch' `[$]{2}[{]testing[}]`,'buster' `[$]{2}[{]project[}]`,'Live Systems Project'" + +:A~ @title + +:B~ Sobre aquest manual + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Usuari + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Projecte + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Exemples + +<< examples.ssi + +:B~ Apèndix + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/project_bugs.ssi new file mode 100644 index 0000000..153e026 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/project_bugs.ssi @@ -0,0 +1,215 @@ +:B~ Informar dels errors + +1~bugs Informar dels errors + +Live systems està lluny de ser perfecte, però volem que sigui el més +perfecte possible - amb la vostra ajuda. No dubtar d'informar sobre un +error. És millor omplir un informe dues vegades que mai. No obstant això, +aquest capítol inclou recomanacions sobre com presentar bons informes +d'errors. + +Per als impacients + +_* Sempre consultar primer les actualitzacions del estat de la imatge a la +nostra pàgina web a http://live-systems.org/ per a veure els problemes +coneguts. + +_* Abans d'enviar un informe d'errors, sempre tractar de reproduir l'error +amb *{les versions més recents}* de la branca de live-build, live-boot, +live-config i live-tools què utilitzeu (com la darrera versió 4.x de +live-build si s'utilitza live-build 4). + +_* Intentar donar *{la informació més específica possible}* sobre +l'error. Això inclou (almenys) la versió de live-build, live-boot, +live-config i live-tools i la distribució del sistema en viu que s'està +construint. + +2~ Problemes coneguts + +Ja que les distribucions Debian *{testing}* i Debian *{unstable}* són blancs +mòbils, quan s'especifica una d'elles com sistema de destinació, no sempre +és possible construir amb èxit. + +% FIXME: + +Si això és massa difícil, no construir un sistema basat en *{testing}* o +*{unstable}*, sinó més aviat, utilitzar *{stable}*. live-build sempre +construeix la versió *{stable}* per defecte. + +El problemes coneguts es mostren sota la secció 'status' a la nostra pàgina +web a http://live-systems.org/. + +Està fora de l'abast d'aquest manual ensenyar a identificar correctament i +solucionar els problemes dels paquets de les distribucions en +desenvolupament, però, hi ha dues coses que sempre es pot provar: Si la +construcció falla quan la distribució de destinació és *{testing}*, provar +*{unstable}*. Si *{unstable}* tampoc funciona, tornar a *{testing}* i fer un +pin de la versió més recent del paquet que falla de *{unstable}* (veure {APT +pinning}#apt-pinning per a més detalls). + +2~ Reconstruir des de zero + +Per a assegurar-se que un error en particular no és causat per un sistema +mal construït, reconstruir sempre tot el sistema en viu a partir de zero per +veure si l'error és reproduïble. + +2~ Fer servir paquets actualitzats + +La utilització de paquets obsolets pot causar problemes significatius al +tractar de reproduir (i en última instància, arreglar) el +problema. Comprovar que el sistema de construcció està actualitzat i tots +els paquets inclosos en la imatge estan també actualitzats. + +2~collect-information Recopilar informació + +Proporcionar informació suficient amb l'informe. Incloure, com a mínim, la +versió exacta de live-build i els passos per a reproduir-lo. Utilitzar el +sentit comú i proporcionar tota altra informació pertinent si es pensa que +aixó pot ajudar a resoldre el problema. + +Per a treure el màxim profit del informe d'errors, es requereix com a mínim +la informació següent: + +_* Arquitectura del sistema amfitrió + +_* Distribució del sistema amfitrió + +_* Versió de live-build al sistema amfitrió + +_* Versió de /{debootstrap}/ al sistema amfitrió + +_* Arquitectura del sistema en viu + +_* Distribució del sistema en viu + +_* Versió de live-boot al sistema amfitrió + +_* Versió de live-config al sistema amfitrió + +_* Versió de live-tools al sistema amfitrió + +Es pot generar un log del procés de construcció mitjançant l'ordre +#{tee}#. Recomanem fer-ho automàticament amb un script #{auto/build}# (veure +{Gestió d'una configuració}#managing-a-configuration per a més detalls). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Durant l'arrencada, live-boot i live-config emmagatzemen els seus logs a +#{/var/log/live/}#. Comprovar aquest fitxers per a detectar missatges +d'error. + +A més, per a descartar altres errors, sempre és una bona idea comprimir el +directori #{config/}# i pujar-lo a algun lloc (*{no}* enviar-lo com arxiu +adjunt a la llista de correu), perquè puguem tractar de reproduir els errors +que s'han trobat. Si això és difícil (per exemple, a causa de la mida del +arxiu) es pot utilitzar la sortida de #{lb config --dump}# que produeix un +resum del arbre de configuració (és a dir, fa un llistat dels fitxers dins +els subdirectoris de #{config/}#, però no els inclou). + +Recordar que s'ha d'enviar qualsevol log que es produeixi amb la +configuració regional en anglès, per exemple, executar les ordres de +live-build començant per #{LC_ALL=C}# o #{LC_ALL=en_US}#. + +2~ Aïllar el cas que falla, si és possible + +Si pot ser, aïllar el cas que falla al canvi més petit possible que fa que +no funcioni. No sempre és fàcil fer això, per tant, si no es possible fer-ho +pel informe, no preocupar-se. No obstant això, si es planeja bé el cicle de +desenvolupament, i s'utilitzen petits conjunts de canvis suficients per +iteració, es pot ser capaç d'aïllar el problema mitjançant la construcció +d'una configuració 'base' més senzilla que s'ajusti a la configuració +desitjada més el conjunt de canvis que fa que no funcioni. Si es dificil +classificar quins canvis fan que falli, pot ser que s'inclogui massa en cada +conjunt de canvis i s'ha de desenvolupar en petits increments. + +2~ Utilitzar el paquet correcte per a informar de l'error + +Si no és clar quin component és el responsable de l'error o si l'error és +general pel que fa als sistemes vius, es pot omplir un informe d'errors +sobre el pseudopaquet debian-live. + +No obstant això, estarem molt agraïts si s'intenta limitar la recerca segons +el lloc on apareix l'error. + +3~ A l'hora de construir mentre bootstrapping + +live-build crea primer un sistema Debian bàsic amb /{debootstrap}/. Si un +error apareix aquí, comprovar si l'error està relacionat amb un paquet +específic de Debian (el més probable), o si està relacionat a l'eina +bootstraping en si mateixa. + +En ambdós casos, això no és un error del sistema en viu, sinó de Debian en +si mateix i, probablement, no ho podem arreglar directament. Informar del +error sobre l'eina de debootstrapping o el paquet que falla. + +3~ A l'hora de construir, durant la instal·lació de paquets + +live-build instal·la paquets addicionals del arxiu de Debian i en funció de +la distribució Debian utilitzada i de l'estat diari de l'arxiu, pot +fallar. Si un error apareix aquí, comprovar si l'error és també reproduïble +en un sistema normal. + +Si aquest és el cas, no es tracta d'un error del sistema en viu, sinó de +Debian - Informar d'això sobre el paquet que falla. Executar /{debootstrap}/ +per separat de la construcció del sistema Live o executar #{lb bootstrap +--debug}# per a tenir més informació. + +A més, si es fa servir un mirall local i/o qualsevol tipus de proxy i s'està +experimentant algun problema, sempre s'ha de mirar de reproduir-lo fent un +bootstrapping a partir d'un mirall oficial. + +3~ En el moment d'arrencar + +Si la imatge no arrenca, informar a la llista de correu, juntament amb la +informació sol·licitada a {Recopilar informació}#collect-information. No +oblidar-se d'esmentar, com/quan la imatge falla, ja sigui amb virtualització +o maquinari real. Si s'utilitza una tecnologia de virtualització d'algun +tipus, sempre fer la prova amb maquinari real abans d'informar d'un +error. Proporcionar una captura de pantalla de l'error és també molt útil. + +3~ En temps d'execució + +Si un paquet s'ha instal·lat correctament, però falla quan s'executa el +sistema Live, això és probablement un error al sistema en viu. No obstant +això: + +2~ Fer la recerca + +Abans de presentar l'informe d'errors, cercar a la web el missatge d'error o +símptoma que s'està rebent. Ja que és molt poc probable que sigui l'única +persona que té un problema en particular. Sempre hi ha una possibilitat que +hagi estat discutit en un altre lloc i hi hagi una possible solució, pegat o +s'hagi proposat una solució alternativa. + +S'ha de prestar especial atenció a la llista de correu dels sistemes en viu, +així com a la pàgina web, ja que és probable que continguin la informació +més actualitzada. Si aquesta informació existeix, incloure una referènca a +aquesta en l'informe d'errors. + +A més, s'hauria de comprovar les llistes d'errors actuals de live-build, +live-boot, live-config i live-tools per a veure si ja s'ha informat sobre +alguna cosa semblant . + +2~ On informar dels errors + +El ${project} manté un registre de tots els errors en el sistema de +seguiment d'errors de Debian (BTS). per a obtenir informació sobre la +utilització del sistema, es pot consultar https://bugs.debian.org/. També es +poden enviar els informes dels errors mitjançant l'ordre #{reportbug}# del +paquet amb el mateix nom. + +En general, s'ha d'informar dels errors en temps de construcció contra el +paquet live-build, dels errors durant l'arrencada contra live-boot i dels +errors de temps d'execució contra live-config. Si no s'està segur de quin +paquet és l'adequat o es necessita més ajuda abans d'enviar un informe +d'errors, informar contra el pseudopaquet debian-live. Nosaltres ens farem +càrrec d'ell i el reassignarem on sigui procedent. + +Tenir en compte que els errors trobats en les distribucions derivades de +Debian (com Ubuntu i altres) no han de ser enviats al BTS de Debian tret que +puguin ser reproduïts també en sistemes Debian utilitzant paquets oficials +de Debian. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/project_coding-style.ssi new file mode 100644 index 0000000..1c36f71 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/project_coding-style.ssi @@ -0,0 +1,152 @@ +:B~ Estil de Codi + +1~coding-style Estil de Codi + +En aquest capítol es documenta l'estil de codi utilitzat a live systems. + +2~ Compatibilitat + +_* No utilitzar una sintaxi o semàntica que sigui exclusiva de l'intèrpret +d'ordres Bash. Per exemple, l'ús dels arrays. + +_* Utilitzar només el subconjunt POSIX - per exemple, utilitzar $(foo) en +lloc de `foo`. + +_* Es pot comprovar els scripts amb 'sh -n' i 'checkbashisms'. + +_* Assegurar-se que tot el codi funciona amb 'set -e'. + +2~ Indentació + +_* Utilitzar sempre tabuladors en lloc d'espais. + +2~ Ajust de línia + +_* En general, les línies són de 80 caràcters com a màxim. + +_* Utilitzar "l'estil Linux" de salts de línia: + +Mal: + +code{ + + if foo; then + bar + fi + +}code + +Bé: + +code{ + + if foo + then + bar + fi + +}code + +_* El mateix val per a les funcions: + +Mal: + +code{ + + Foo () { + bar + } + +}code + +Bé: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Les variables van sempre en majúscules. + +_* Les variables que s'utilitzen a live-build sempre comencen amb el prefix +#{LB_}# + +_* Les variables temporals internes de live-build comencen amb el prefix +#{\_LB_}# + +_* Les variables locals comencen amb el prefix live-build #{\_\_LB_}# + +_* Les variables en relació a un paràmetre d'arrencada de live-config +comencen amb #{LIVE_}#. + +_* Totes les altres variables de live-config comencen amb el prefix #{_}# + +_* Utilitzar claus al voltant de les variables, per exemple, escriure +#{${FOO}}# en lloc de #{$FOO}#. + +_* Protegir sempre les variables amb cometes per a respectar els espais en +blanc potencials: escriure #{"${FOO}"}# no #{${FOO}}#. + +_* Per raons de coherència, utilitzar sempre cometes al assignar valors a +les variables: + +Mal: + +code{ + + FOO=bar + +}code + +Bé: + +code{ + + FOO="bar" + +}code + +_* Si s'utilitzen múltiples variables, posar cometes a l'expressió completa: + +Mal: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Bé: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscel·lània + +_* Utilitzar "#{|}#" (sense les cometes) com separador en l'ús de sed, per +exemple, "#{sed -e 's|foo|bar|'}#" (sense ""). + +_* No utilitzar l'ordre #{test}# per a fer comparacions o tests, utilitzar +"#{[}#" "#{]}#" (sense ""); per exemple, "#{if [ -x /bin/foo ]; ...}#" i no +"#{if test -x /bin/foo; ...}#". + +_* Utilitzar #{case}# sempre que sigui possible en lloc de #{test}#, ja que +és més fàcil de llegir i més ràpid en l'execució. + +_* Fer servir noms en majúscula per a les funcions per evitar conflictes amb +l'entorn dels usuaris. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/project_contributing.ssi new file mode 100644 index 0000000..ecb3573 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/project_contributing.ssi @@ -0,0 +1,119 @@ +:B~ Contribuir al projecte + +1~contributing-to-project Contribuir al projecte + +Quan s'envia una contribució, s'ha d'identificar clarament el titular dels +drets d'autor i incloure la declaració de concessió de llicències +aplicables. Recordar que per a ser acceptada, la contribució ha de tenir una +llicencia igual que la resta del document, a saber, la versió de la GPL 3 o +superior. + +Les contribucions al projecte, com ara traduccions i pegats, són molt +benvingudes. Qualsevol persona pot fer un lliurament directe al +repositori. No obstant això, demanem que s'enviïn els canvis grans a la +llista de correu per a parlar-ne en primer lloc. Veure la secció +{Contacte}#contact per a més informació. + +El ${project} utilitza Git com a sistema de control de versions i gestió de +codi font. Com s'explica en {Repositoris Git}#git-repositories hi ha dues +branques principals de desenvolupament: *{debian}* i *{debian-next}*. Tothom +pot fer lliuraments a les branques debian-next dels repositoris live-boot, +live-build, live-config, live-images, live-manual i live-tools. + +No obstant això, hi ha certes restriccions. El servidor rebutja: + +_* Push que no són fast-forward. + +_* Commits merge. + +_* Afegir o eliminar etiquetes o branques. + +Tot i que tots els lliuraments poden ser revisats, demanem que s'utilitzi el +sentit comú i es facin bons lliuraments amb bons missatges. + +_* Escriure missatges de lliurament que consisteixen en oracions completes i +significatives en anglès, començant amb una lletra majúscula i acabant amb +un punt. En general, aquests començaran amb la forma +'Fixing/Adding/Removing/Correcting/Translating/...'. + +_* Escriure bons missatges de lliurament. La primera línia ha de ser un +resum exacte dels continguts del lliurament, que s'inclourà en la llista de +canvis. Si es necessita fer algunes explicacions més, escriure a sota +deixant una línia en blanc després de la primera línea i després una altra +línia en blanc després de cada paràgraf. Les línies dels paràgrafs no han de +superar els 80 caràcters de longitud. + +_* Fer lliuraments de manera atòmica, és a dir, no barrejar coses no +relacionades en el mateix lliurament. Fer un lliurament diferent per a cada +canvi que es faci. + +2~ Fer canvis + +Per tal de fer un push als repositoris, s'ha de seguir el següent +procediment. Aquí s'utilitza live-manual com a exemple, per tant, cal +substituir-lo pel nom del repositori amb que es desitja treballar. Per a +obtenir informació detallada sobre com editar live-manual veure {Contribuir +a aquest document}#how-to-contribute. + +_* Obtenir la clau pública: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Afegir la següent secció a la configuració del vostre openssh-client: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Fer una còpia del manual a través de ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Assegurar-se de tenir el autor i el correu electrònic configurats al Git: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Important:}* Tenir en compte que s'han d'enviar els canvis a la branca *{debian-next}*. + +_* Fer els canvis. En aquest exemple s'hauria d'escriure primer una nova +secció sobre aplicar pegats i després preparar-se per a afegir els fitxers i +escriure el missatge de la següent manera: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Fer un push al servidor: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/project_git.ssi new file mode 100644 index 0000000..517012b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/project_git.ssi @@ -0,0 +1,86 @@ +:B~ Repositoris Git + +1~git-repositories Repositoris Git + +La llista de tots els repositoris del ${project} és a +http://live-systems.org/gitweb/. Les URLs git del projecte tenen la forma: +#{protocol://live-systems.org/git/repositori}#. Per tant, per a clonar +live-manual en només lectura, llançar: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +O, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +O, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +Les adreces per a clonar amb permís d'escriptura tenen la forma: +#{git@live-systems.org/repositori}#. + +Així que, de nou, per a clonar live-manual a través de ssh escriure: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +L'arbre git es compon de diverses branques diferents. Les branques +*{debian}* i *{debian-next}* són particularment notables perquè contenen el +treball real que, amb el temps, serà inclòs en cada nova versió. + +Després de clonar qualsevol dels repositoris existents, estarem a la branca +*{debian}*. Això és apropiat per a fer una ullada a l'estat de l'última +versió del projecte, però abans de començar a treballar és fonamental +canviar a la branca *{debian-next}*. Per fer això: + +code{ + + $ git checkout debian-next + +}code + +La branca *{debian-next}*, que no sempre és fast-forward, és on es realitzen +tots els canvis abans de fusionar-los amb la branca *{debian}*. Per fer una +analogia, és com un camp de proves. Si s'està treballant en aquesta branca i +es necessari fer un pull, s'haurà de fer un #{git pull --rebase}# perquè les +modificacions locals es guardin mentre s'actualitza des del servidor i +llavors els canvis locals es posaran al damunt de tot. + +2~ Gestió de múltiples repositoris + +Si es té la intenció de clonar diversos repositoris de Live Systems i +canviar a la branca *{debian-next}* immediatament per a comprovar l'últim +codi, escriure un pegat o contribuir amb una traducció, s'ha de saber que el +servidor git proporciona un fitxer #{mrconfig}# per a facilitar el maneig de +múltiples repositoris. Per a utilitzar-lo cal instal·lar el paquet /{mr}/ i +després d'això, fer: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +Aquesta ordre automàticament clonarà i canviarà a la branca *{debian-next}* +els repositoris de desenvolupament dels paquets debian produïts pel +projecte. Aquests inclouen, entre d'altres, el repositori live-images, que +conté les configuracions utilitzades per a construir les imatges +prefabricades que el projecte publica per a l'ús general. per a obtenir més +informació sobre com utilitzar aquest repositori, consultar {Clonar una +configuració publicada via Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/project_procedures.ssi new file mode 100644 index 0000000..08720e5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/project_procedures.ssi @@ -0,0 +1,101 @@ +:B~ Procediments + +1~procedures Procediments + +Aquest capítol documenta els procediments dins del ${project} per a les +diferents tasques que necessiten la cooperació amb altres equips de Debian. + +2~ Publicacions majors + +El llançament d'una nova versió de Debian inclou una gran quantitat de +diferents equips que treballen junts per a fer que aixó succeeixi. En algun +moment, l'equip Live arriba i construeix imatges en viu del sistema. Els +requisits per a fer això són: + +_* Un mirall que contingui les versions publicades dels arxius de debian i +debian-security on pugui accedir el buildd de debian-live. + +_* S'ha de conèixer el nom de la imatge (per exemple, +debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* S'han de sincronitzar les dades de debian-cd (udeb exclude lists). + +_* Les imatges es construeixen i s'en fa una rèplica a cdimage.debian.org. + +2~ Publicacions puntuals + +_* Un cop més, necessitem miralls actualitzats de debian i debian-security. + +_* Les imatges es construeixen i s'en fa una rèplica a cdimage.debian.org. + +_* Enviar un anunci per correu electrònic. + +3~ Ùltima publicació puntual d'una versió de Debian + +Recordar que s'han d'ajustar els miralls chroot i binary en la construcció +de l'última sèrie d'imatges per a una versió de Debian després de +canviar-les de ftp.debian.org a archive.debian.org. D'aquesta manera, les +imatges prefabricades ja velles continuaran sent útils sense modificacions +per part dels usuaris. + +3~ Plantilla per a anunciar una publicació puntual + +Es pot generar un correu per a anunciar una publicació puntual mitjançant la +plantilla següent i l'ordre: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Llegir el correu acuradament abans d'enviar-lo i passar-lo als altres per a +la correcció d'errades. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_basics.ssi new file mode 100644 index 0000000..ee090ed --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_basics.ssi @@ -0,0 +1,664 @@ +:B~ Conceptes bàsics + +1~the-basics Conceptes bàsics + +Aquest capítol conté una breu descripció del procés de construcció i les +instruccions per a l'utilització dels tres tipus d'imatge més comunes. El +tipus d'imatge més versàtil #{iso-hybrid}# es pot utilitzar en una màquina +virtual, en un medi òptic o qualsevol altre dispositiu d'emmagatzematge +USB. En certs casos especials, com s'explica més endavant, el tipus #{hdd}# +pot ser el més adequat. El capítol conté instruccions detallades per a la +construcció d'una imatge tipus #{netboot}#, que és una mica més complicat a +causa de la configuració necessària en el servidor. Aquest és un tema una +mica avançat per a algú que no està familiaritzat ja amb l'arrencada en +xarxa, però s'inclou aquí perquè un cop que la configuració es porta a +terme, es tracta d'una manera molt convenient per a provar i desplegar +imatges per a l'arrencada en xarxa local sense la molèstia de tractar amb +els dispositius de les imatges. + +La secció acaba amb una breu introducció al {webbooting}#webbooting que és, +potser, la forma més fàcil d'utilitzar imatges diferents per a diferents +propòsits, canviant d'una a l'altra segons sigui necessari, utilitzant +internet com un mitjà. + +Al llarg del capítol, sovint es fa referència als noms dels fitxers produïts +per defecte per live-build. Si es {descarrega una imatge +prefabricada}#downloading-prebuilt-images, els noms dels fitxers poden ser +direrents. + +2~what-is-live Què és un sistema viu? + +Un sistema viu és un sistema operatiu que arrenca en un equip des d'un +dispositiu extraïble, com un CD-ROM o una memòria USB o des d'una xarxa, a +punt per a fer servir sense cap tipus d'instal·lació en la unitat(s) +habitual(s), amb una configuració automàtica feta en temps d'execució (veure +{Termes}#terms). + +Amb live systems, és un sistema operatiu, construït per a una de les +arquitectures suportades (actualment amd64 i i386). Conté les següents +parts: + +_* *{Imatge del nucli Linux}*, generalment s'anomena #{vmlinuz*}# + +_* *{Imatge del disc RAM inicial (initrd)}*: un disc RAM configurat per a +l'arrencada de Linux, que conté els mòduls que possiblement es necessitaran +per a muntar la imatge del sistema i algunes seqüències d'ordres per a +fer-ho. + +_* *{Imatge del sistema}*: Imatge del sistema de fitxers del sistema +operatiu. Normalment, s'utilitza un sistema de fitxers comprimit SquashFS +per a minimitzar la mida de la imatge. Tenir en compte que és de només +lectura. Així, durant l'arrencada, el sistema Debian Live utilitzarà el disc +RAM i un mecanisme de "unió" per a permetre l'escriptura de fitxers en el +sistema en funcionament. No obstant això, totes les modificacions es perdran +al apagar l'equip si no és que s'utilitza la persistència opcional (vegeu +{Persistència}#persistence). + +_* *{Carregador d'arrencada }*: Una petita peça de codi dissenyat per a +arrencar des del medi triat, possiblement presentant un indicador +d'arrencada o un menú per a permetre la selecció +d'opcions/configuració. Carrega el nucli de Linux i el seu initrd per a +funcionar amb un sistema de fitxers del sistema associat. Es poden utilitzar +diverses solucions, en funció del medi de destinació i el format del sistema +de fitxers que conté els components esmentats anteriorment: isolinux per a +arrencar des de CD o DVD en format ISO9660, syslinux per a una unitat USB o +HDD que s'iniciarà des de particions VFAT, extlinux per a particions +ext2/3/4 i btrfs, pxelinux per a PXE netboot, GRUB per a particions +ext2/3/4, etc. + +Es pot utilitzar live-build per a construir la imatge del sistema amb +especificacions pròpies, configurar un nucli de Linux, el initrd, i un +carregador d'arrencada per a executar-los, tot això en un format depenent +del medi (imatge ISO9660, imatge de disc, etc.). + +2~downloading-prebuilt-images Descàrrega d'imatges prefabricades + +Si bé l'objectiu d'aquest manual és el desenvolupament i la construcció +d'imatges en viu pròpies, es pot simplement voler provar una de les nostres +imatges prefabricades, ja sigui com una introducció al seu ús o a la +construcció d'imatges personalitzades. Aquestes imatges estan construïdes +utilitzant el nostre {repositori git +live-images}#clone-configuration-via-git i les versions oficials estables es +publiquen a https://www.debian.org/CD/live/. A més, les versions antigues i +les futures, i les imatges no oficials que contenen microprogramari i +controladors no lliures estan disponibles a +http://live-systems.org/cdimage/release/. + +2~using-web-builder Ús del servei de construcció d'imatges en viu web + +Com un servei a la comunitat, oferim un servei web capaç de construïr +imatges en viu a http://live-systems.org/build/. Aquest lloc es mantingut +sobre una base del millor esforç. És a dir, encara que ens esforcem per a +mantenir-lo al dia i que estigui operatiu en tot moment, i de fer anuncis +d'interrupcions importants del servei, no podem garantir una disponibilitat +del 100% o una creació d'imatges ràpida. Tanmateix, el servei pot tenir, de +tant en tant, problemes que triguin algun temps en resoldre's. Si es té +problemes o preguntes sobre aquest servei, posar-se en {contacte amb +nosaltres}#contact, proporcionant l'enllaç a la pàgina web de la imatge +construïda. + +3~ Ús i advertències sobre el servei web + +La interfície web actualment no pot prevenir l'ús de combinacions d'opcions +no vàlides, i en particular, quan el canvi d'una opció que normalment (és a +dir, utilitzant live-build directament) canviaria els valors predeterminats +d'altres opcions que figuren en el formulari de la web, el constructor web +no canvia aquests valors predeterminats. En particular, si es canvia +#{--architectures}# del valor per defecte #{i386}# a #{amd64}#, s'ha de +canviar l'opció corresponent #{--linux-flavours}# del valor per defecte +#{586}# a #{amd64}#. Veure la pàgina del manual #{lb_config}# per a la +versió de live-build instal·lada al constructor web per a més detalls. El +nombre de la versió de live-build apareix a la part inferior de la pàgina +web. + +El càlcul de temps donat pel constructor web és només una estimació +aproximada i pot no reflectir acuradament el temps que realment es necessita +per a finalitzar la construcció d'una imatge. Tenir en compte que aquesta +estimació tampoc s'actualitza tal i com va passant el temps. Cal tenir una +mica de paciència. No tornar a carregar la pàgina després de enviar la +proposta de construcció, ja que això pot tornar a reenviar una nova petició +amb els mateixos paràmetres. Posar-se {en contacte amb nosaltres}#contact si +no es rep la notificació de la construcció un cop que s'estigui segur que +s'ha esperat prou i verificat que la notificació per correu electrònic no ha +anat a parar al spam. + +El servei web està limitat en el tipus d'imatges que es poden +construir. Això el manté simple i eficient d'utilitzar i mantenir. Si es +desitja realitzar personalitzacions que no es contemplen en la interfície +web, a la resta d'aquest manual s'explica com crear imatges pròpies amb +live-build. + +2~building-iso-hybrid Primers passos: construcció d'una imatge ISO híbrida + +Independentment del tipus d'imatge, s'haurà de fer els mateixos passos +bàsics per a construir una imatge cada vegada. Com a primer exemple, crear +un directori de treball, canviar a aquest directori i executar la següent +seqüència d'ordres live-build per a crear una imatge ISO híbrida de base que +conté només el sistema per defecte de Debian sense X.org. És adequat per a +gravar en un CD o DVD, i també per a copiar en una memòria USB. + +El nom del directori de treball és absolutament indiferent, però si es fa un +cop d'ull als exemples utilitzats a live-manual, és una bona idea utilitzar +un nom que ajudi a identificar la imatge amb que s'està treballant en cada +directori, especialment si s'està treballant o experimentant amb diferents +tipus d'imatges. En aquest cas, anem a construir un sistema per defecte així +que l'anomenarem, per exemple, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Aleshores, executar l'ordre #{lb config}#. Això crearà una jerarquia +«config/» en el directori actual per a ser utilitzada per altres ordres: + +code{ + + $ lb config + +}code + +Aquí no es passa cap paràmetre a aquestes ordres, per tant s'utilitzaran les +opcions per defecte. Veure {L'ordre lb config}#lb-config per a més detalls. + +Ara que la jerarquia «config/» ja existeix, crear la imatge amb l'ordre #{lb +build}#: + +code{ + + # lb build + +}code + +Aquest procés tardarà una mica, depenent de la velocitat del ordinador i de +la connexió de la xarxa. Quan hagi acabat, ha d'haver un fitxer imatge +#{live-image-i386.hybrid.iso}#, a punt per a ser utilitzat, en el directori +actual. + +*{Nota:}* Si s'està construint en un sistema amd64 el nom de la imatge resultant serà #{live-image-amd64.hybrid.iso}#. Tenir en compte aquesta convenció al llarg del manual. + +2~using-iso-hybrid Usar una imatge ISO híbrida en viu + +Després de la construcció o la descàrrega d'una imatge ISO híbrida, que pot +ser obtinguda a https://www.debian.org/CD/live/, el següent pas habitual és +preparar el dispositiu per a l'arrencada, ja sigui medis òptics com un +CD-R(W) o DVD-R(W) o una memòria USB. + +3~burning-iso-image Gravar una imatge ISO en un medi físic + +Gravar una imatge ISO és fàcil. Simplement cal instal·lar /{xorriso}/ i +utilitzar-lo des de la línia d'ordres per a gravar la imatge. Per exemple: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copiar una imatge ISO híbrida en un dispositiu +USB + +Les imatges ISO preparades amb #{xorriso}#, és poden copiar directament a +una memòria USB utilitzant el programa #{cp}# o un altre +d'equivalent. Connectar una memòria USB amb una mida prou gran per al fitxer +de la imatge i determinar quin dispositiu és, que d'ara endavant anomenarem +#{${USBSTICK}}#. Aquest és el dispositiu de la memòria, com per exemple +#{/dev/sdb}#, i no una partició, com ara #{/dev/sdb1}#! Es pot trobar el nom +del dispositiu correcte mirant la sortida de #{dmesg}# després de connectar +la memòria usb, o encara millor, #{ls -l /dev/disk/by-id}#. + +Quan s'estigui segur de tenir el nom del dispositiu correcte, utilitzar +l'ordre #{cp}# per a copiar la imatge a la memòria. *{Fent això es perdran +definitivament tots els continguts anteriors de la memòria usb!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Nota:}* L'ordre /{sync}/ s'utilitza per a assegurar-se que totes les dades, que el nucli emmagatzema en la memòria durant la còpia de la imatge, s'escriuen en el dispositiu USB. + +3~using-usb-extra-space Utilitzar l'espai lliure en una memòria USB + +Després de copiar la #{live-image-i386.hybrid.iso}# en un dispositiu USB, la +primera partició serà utilitzada pel sistema en viu. Per a poder utilitzar +l'espai que queda lliure es pot utilitzar una eina de particionament com +/{gparted}/ o /{parted}/ per a crear una nova partició. + +code{ + + # gparted ${USBSTICK} + +}code + +Després de crear la partició, on #{${PARTITION}}# és el nom de la partició, +com ara #{/dev/sdb2}#, s'ha de crear un sistema de fitxers. Una opció +possible seria ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Nota:}* Si es vol utilitzar l'espai addicional amb Windows, pel que sembla, aquest sistema operatiu normalment no pot accedir a altres particions més que a la primera. Algunes solucions a aquest problema han estat discutides a la nostra {llista de correu}#contact, però sembla que no hi ha respostes fàcils. + +*{Recordar: Cada vegada que s'instal·li una nova live-image-i386.hybrid.iso al dispositiu, es perdran totes les dades perquè la taula de particions se sobreescriu amb el contingut de la imatge, de manera que es assenyat fer una còpia de seguretat de la partició addicional per a restaurar les dades de nou després d'actualitzar la imatge en viu.}* + +3~booting-live-medium Arrencar el medi en viu + +La primera vegada que s'arrenqui el medi en viu, ja sigui des de CD, DVD, +memòria USB, o PXE, pot ser necessaria alguna petita configuració al BIOS +del ordinador en primer lloc. Atès que les BIOS varien molt en les seves +funcions i dreceres de teclat, no podem entrar en el tema en profunditat +aquí. Algunes BIOS proporcionen una tecla per a obrir un menú de dispositius +d'arrencada, que és la manera més fàcil si es troba disponible al +sistema. En cas contrari, cal entrar al menú de configuració del BIOS i +canviar l'ordre d'arrencada per a situar el dispositiu del sistema en viu +abans que el dispositiu d'arrencada normal. + +Després d'arrencar des del dispositiu, es veurà un menu d'inici. Si es prem +«entrer» el sistema s'iniciarà amb l'entrada #{Live}# i les seves opcions +per defecte. Per a obtenir més informació sobre les opcions d'arrencada, +llegir «l'ajuda» (help) al menú i també les pàgines del manual de live-boot +i live-config que es troben dins del sistema en viu. + +Suposant que s'ha seleccionat #{Live}# i s'ha arrencat una imatge +d'escriptori per defecte, després que els missatges d'arrencada hagin passat +s'haurà iniciat una sessió com a usuari #{user}# i es veurà un escriptori, a +punt per a ser utilitzat. Si s'ha arrencat una imatge de només consola, com +per exemple una imatge #{standard}# de les {imatges +prefabricades}#downloading-prebuilt-images, s'iniciarà una sessió com a +usuari #{user}# i es veurà el indicador de la shell, a punt per a ser +utilitzat. + +2~using-virtual-machine Utilitzar una màquina virtual per a fer proves + +Pot ser un gran estalvi de temps per al desenvolupament d'imatges en viu +executar-les en una màquina virtual (VM). Això no està exempt +d'advertiments: + +_* L'execució d'una màquina virtual requereix de suficient memòria RAM, tant +per al sistema operatiu convidat i l'amfitrió i es recomana una CPU amb +suport de maquinari per a la virtualització. + +_* Hi ha algunes limitacions inherents a l'execució en una màquina virtual, +per exemple, rendiment de vídeo pobre, opcions limitadades de maquinari +emulat. + +_* En el desenvolupament per a un maquinari específic, no hi ha cap +substitut millor que el propi maquinari. + +_* De tant en tant hi ha errors que només sorgeixen durant l'execució en una +màquina virtual. En cas de dubte, comprovar la imatge directament al +maquinari. + +Sempre que es pugui treballar dins d'aquestes limitacions, examinar el +programari de màquina virtual disponible i triar un que sigui adequat per a +les necessitats pròpies. + +3~testing-iso-with-qemu Provar una imatge ISO amb QEMU + +La màquina virtual més versàtil dins Debian és QEMU. Si el processador té +suport de maquinari per a la virtualització, utilitzar el paquet +/{qemu-kvm}/; la descripció del paquet /{qemu-kvm}/ enumera breument els +requisits. + +Primer, instal·lar /{qemu-kvm}/ si el processador ho suporta. Si no, +instal·lar /{qemu}/, en aquest cas el nom del programa és #{qemu}# en lloc +de #{kvm}# en els exemples següents. El paquet /{qemu-utils}/ també és +valuós per a la creació d'imatges de disc virtuals amb #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Arrencar una imatge ISO és senzill: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +Veure les pàgines del manual per a més detalls + +3~testing-iso-with-virtualbox Provar una imatge ISO amb VirtualBox + +Per a provar la ISO amb /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Crear una nova màquina virtual, canviar els paràmetres d'emmagatzematge per +a utilitzar #{live-image-i386.hybrid.iso}# com unitat de CD/DVD i arrencar +la màquina. + +*{Nota:}* Per a provar sistemes vius que contenen X.org amb /{virtualbox}/, segurament es assenyat incloure el paquet del driver VirtualBox X.org, /{virtualbox-guest-dkms}/ i /{virtualbox-guest-x11}/, en la configuració de live-build. En cas contrari, la resolució es limita a 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +Per tal de fer que el paquet dkms funcioni, s'han d'instal·lar també les +capçaleres del nucli per a la variant del nucli de la imatge. En lloc +d'enumerar manualment el paquet /{linux-headers}/ correcte en la llista de +paquets creat anteriorment, la selecció del paquet adequat es pot fer +automàticament amb live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Construir i utilitzar una imatge HDD + +Construir una imatge HDD és similar a una ISO híbrida en tots els aspectes, +excepte que s'especifica #{-b hdd}#, que el nom del fitxer resultant és +#{live-image-i386.img}# i que no es pot gravar en medis òptics. És adequada +per a arrencar des de dispositius USB, discs durs USB, i altres dispositius +d'emmagatzematge portàtils. Normalment, una imatge ISO híbrida es pot +utilitzar per a aquest propòsit en el seu lloc, però si el BIOS no maneja +adequadament les imatges híbrides, cal utilitzar una imatge HDD. + +*{Nota:}* si s'ha creat una imatge ISO híbrida amb l'exemple anterior, s'haurà de netejar el directori de treball amb l'ordre #{lb clean}# (veure {L'ordre lb clean}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Executar l'ordre #{lb config}# com abans, excepte que aquesta vegada +especificant el tipus d'imatge HDD: + +code{ + + $ lb config -b hdd + +}code + +Ara construir la imatge amb l'ordre #{lb build}#: + +code{ + + # lb build + +}code + +Quan la construcció acabi, hauria d'haver un fitxer #{live-image-i386.img}# +al directori actual. + +La imatge binària generada conté una partició VFAT i el carregador +d'arrencada syslinux, llestos per a ser escrits directament a una memòria +USB. Un cop més, donat que l'ús d'una imatge HDD és com utilitzar una imatge +ISO híbrida en un USB, seguir les instruccions de {Usar una imatge ISO +híbrida en viu}#using-iso-hybrid, però amb el nom de fitxer +#{live-image-i386.img}# en lloc de #{live-image-i386.hybrid.iso}#. + +Igualment, per a provar una imatge HDD amb Qemu, instal·lar /{qemu}/ com +s'ha descrit anteriorment a {Provar una imatge ISO amb +QEMU}#testing-iso-with-qemu. A continuació, executar #{kvm}# o #{qemu}#, +segons la versió instal·lada al sistema amfitrió, especificant +#{live-image-i386.img}# com a primer disc dur. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Construir una imatge netboot + +La següent seqüència d'ordres crearà una imatge netboot bàsica que conté el +sistema per defecte de Debian sense X.org. És adequada per a l'arrencada en +xarxa. + +*{Nota:}* si s'ha realitzat algun dels exemples anteriors, s'haurà de netejar el directori de treball amb l'ordre #{lb clean}#: + +code{ + + # lb clean + +}code + +En aquest cas concret, un #{lb clean --binary}# no seria suficient per a +netejar les etapes necessàries. La causa d'això és que en les configuracions +d'arrencada en xarxa, es necessita una configuració initramfs diferent que +live-build realitza automàticament quan es construeixen imatges netboot. Ja +que la creació del initramfs pertany a l'etapa chroot, fer el canvi a +netboot en un directori de construcció existent significa reconstruir +l'etapa chroot també. Per tant, s'ha de fer un #{lb clean}# (que eliminarà +l'etapa chroot, també) + +Executar l'ordre següent per a configurar la imatge per a arrencar en xarxa: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +A diferència de les imatges ISO i HDD, l'arrencada en xarxa no serveix el +sistema de fitxers al client, per tant els fitxers han de ser servits a +través de NFS. Amb lb config es poden elegir diferents sistemes de fitxers +de xarxa. Les opcions #{--net-root-path}# i #{--net-root-server}# +especifiquen la ubicació i el servidor, respectivament, del servidor NFS on +es troba la imatge del sistema de fitxers a l'hora d'arrencar. Assegurar-se +que aquests s'ajusten als valors adequats per a la xarxa i el servidor. + +Ara construir la imatge amb l'ordre #{lb build}#: + +code{ + + # lb build + +}code + +En l'arrencada en xarxa, el client executa una petita peça de programari que +normalment es troba a la EPROM de la targeta Ethernet. Aquest programa envia +una petició DHCP per a obtenir una adreça IP i la informació sobre què fer a +continuació. Per regla general, el següent pas és aconseguir un carregador +d'arrencada de més alt nivell a través del protocol TFTP. Podria ser GRUB, +pxelinux o fins i tot arrencar directament a un sistema operatiu com Linux. + +Per exemple, si es descomprimeix el arxiu #{live-image-i386.netboot.tar}# +generat al directori #{/srv/debian-live}#, es trobarà la imatge del sistema +de fitxers a #{live/filesystem.squashfs}# i el nucli, initrd i carregador +d'arrencada pxelinux a #{tftpboot/}#. + +Ara hem de configurar els tres serveis al servidor per a l'arrencada en +xarxa: el servidor DHCP, servidor TFTP i el servidor NFS. + +3~ Servidor DHCP + +S'ha de configurar el servidor DHCP de la xarxa per a assegurar-se que dona +una adreça IP per al client del sistema d'arrencada en xarxa, i per a +anunciar la ubicació del carregador d'arrencada PXE. + +Heus aquí un exemple per a servir d'inspiració, escrit per al servidor ISC +DHCP #{isc-dhcp-server}# al fitxer de configuració #{/etc/dhcp/dhcpd.conf}#: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Servidor TFTP + +Aquest serveix el nucli i el disc ram inicial per al sistema en temps +d'execució. + +S'ha d'instal·lar el paquet /{tftpd-hpa}/. Aquest pot servir tots els +fitxers continguts dins d'un directori arrel, per regla general +#{/srv/tftp}#. Per tal que es serveixin els fitxers dins de +#{/srv/debian-live/tftpboot}#, s'ha d'executar com a superusuari la següent +ordre: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +i omplir el nou directori del servidor tftp quan ho hàgim de fer. + +3~ Servidor NFS + +Un cop l'ordinador ha descarregat, ha arrencat el nucli de Linux i ha +carregat el initrd, intentarà muntar la imatge del sistema de fitxers en viu +a través d'un servidor NFS. + +S'ha d'instal·lar el paquet /{nfs-kernel-server}/ + +Llavors, fer que la imatge del sistema de fitxers estigui disponible a +través de NFS afegint una línia com la següent a #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +i informar al servidor NFS sobre aquesta nova exportació amb la següent +ordre: + +code{ + + # exportfs -rv + +}code + +La configuració d'aquests tres serveis pot ser una mica difícil. És possible +que es necessiti una mica de paciència per a aconseguir que tots tres +funcionin plegats. Per a obtenir més informació, veure el wiki de syslinux a +http://www.syslinux.org/wiki/index.php/PXELINUX o la secció TFTP Net Booting +al Manual del Instal·lador de Debian a +http://d-i.alioth.debian.org/manual/ca.i386/ch04s05.html. Això pot ajudar, +ja que els seus processos són molt similars. + +3~ Com provar l'arrencada en xarxa + +La creació d'imatges d'arrencada en xarxa es senzilla amb live-build, però +provar les imatges en màquines físiques pot costar molt de temps. + +Per a fer la nostra vida més fàcil, podem utilitzar la virtualització. + +3~ Qemu + +_* Instal·lar /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Editar #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Descarregar o crear un #{grub-floppy-netboot}#. + +Llançar #{qemu}# amb "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting és una manera convenient d'aconseguir i arrencar sistemes vius +utilitzant internet com un mitjà. Els requisits per fer webbooting són molt +pocs. D'una banda, es necessita un dispositiu amb un carregador d'arrencada, +un disc ram inicial i un nucli. D'altra banda, un servidor web per +emmagatzemar els fitxers squashfs que contenen el sistema de fitxers. + +3~ Obtenir els fitxers webboot + +Com de costum, es pot construir les imatges un mateix o utilitzar els +fitxers prefabricats, que estan disponibles a la pàgina principal del +projecte a http://live-systems.org/. Les imatges prefabricades són adients +per fer proves inicials fins que un pugui afinar les seves pròpies +necessitats. Si ja s'ha construït una imatge en viu, els fitxers necessaris +pel webbooting es troben al directori de construcció sota +#{binary/live/}#. Els fitxers s'anomenen #{vmlinuz}#, #{initrd.img}# i +#{filesystem.squashfs}#. + +També és possible extreure els fitxers d'una imatge iso ja existent. Per tal +d'aconseguir això, muntar la imatge de la següent manera: + +code{ + + # mount -o loop image.iso /mnt + +}code + +Els fitxers es troben sota el directori #{live/}#. En aquest cas concret, +seria #{/mnt/live/}#. Aquest mètode té el desavantatge que cal ser root per +poder muntar la imatge. No obstant això, té l'avantatge que és fàcil de fer +amb un script, i per tant es pot automatitzar. + +Però, sens dubte, la forma més fàcil d'extreure els fitxers d'una imatge iso +i pujar-los al servidor web a la vegada, és utilitzant el midnight commander +o /{mc}/. Si es té el paquet /{genisoimage}/ instal·lat, aquest gestor de +fitxers de dos panells permet examinar el contingut d'un arxiu iso en un +panell i pujar els fitxers via ftp en l'altre panell. Tot i que aquest +mètode requereix fer un treball manual, no requereix privilegis de root. + +3~ Arrencar imatges webboot + +Mentre que alguns usuaris prefereixen utilitzar la virtualització per prova +el webbooting, en aquest cas utilitzem maquinari real perquè coincideixi amb +el següent cas d'ús, que només ha de ser considerat com un exemple. + +Per a arrencar una imatge webboot és suficient tenir els components +esmentats anteriorment, és a dir, #{vmlinuz}# i #{initrd.img}# en una +memòria usb dins d'un directori anomenat #{live/}# i instal·lar syslinux com +a gestor d'arrencada. Després, arrencar des de la memòria usb i escriure +#{fetch=URL/RUTA/AL/FITXER}# a les opcions d'arrencada. live-boot +descarregarà l'arxiu squashfs i l'emmagatzemarà en la memòria ram. D'aquesta +manera, és possible utilitzar el sistema de fitxers comprimit descarregat +com si fos un sistema viu normal. Per exemple: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Cas d'ús:}* Tenir un servidor web en el qual s'ha emmagatzemat dos arxius squashfs, un que conté un escriptori complet, com ara gnome, i un standard. Si es necessita un entorn gràfic per a una màquina, es pot connectar la memòria usb i arrencar la imatge gnome. Si es necessita una de les eines que s'inclouen en el segon tipus d'imatge, potser per a una altra màquina, arrencar des de internet la imatge standard. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-binary.ssi new file mode 100644 index 0000000..7dfd094 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-binary.ssi @@ -0,0 +1,67 @@ +:B~ Personalització de la imatge binària + +1~customizing-binary Personalització de la imatge binària + +2~ Carregadors d'arrencada + +live-build utilitza /{syslinux}/ i alguns dels seus derivats (depenent del +tipus d'imatge) com carregadors d'arrencada per defecte. Es poden +personalitzar fàcilment per satisfer totes les necessitats. + +Per a utilitzar un tema complet, copiar +#{/usr/share/live/build/bootloaders}# a #{config/bootloaders}# i editar els +fitxers allí. Si no es vol modificar totes les configuracions dels +carregadors d'arrencada disponibles, només cal utilitzar una còpia local +personalitzada d'un dels carregadors, per exemple, copiar la configuració +d'*{isolinux}* a #{config/bootloaders/isolinux}# ja és suficient, depenent +del cas d'ús. + +Quan es modifica un dels temes per defecte, si es vol utilitzar una imatge +de fons personalitzada que es mostrarà juntament amb el menú d'arrencada, es +pot afegir una imatge de 640x480 píxels. Aleshores, esborrar el fitxer +splash.svg. + +Hi ha moltes possibilitats a l'hora de fer canvis. Per exemple, els derivats +de syslinux estan configurats per defecte amb un temps d'espera de 0 (zero) +el que significa que faran una pausa indefinida en la seva pantalla inicial +fins que es premi una tecla. + +Per a modificar el temps d'espera d'arrencada d'una imatge #{iso-hybrid}# es +pot editar el fitxer *{isolinux.cfg}* especificant el temps d'espera en +unitats de segons 1/10. Un fitxer *{isolinux.cfg}* modificat per a arrencar +després de cinc segons seria semblant a aquest: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ metadades ISO + +Quan es crea una imatge binària ISO9660, es poden utilitzar les següents +opcions per a afegir diverses metadades textuals. Això pot ajudar a +identificar fàcilment la versió o la configuració d'una imatge sense +arrencar-la. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: Ha de descriure +l'aplicació que serà a la imatge. La longitud màxima per a aquest camp és de +128 caràcters. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: Ha de descriure al preparador de +la imatge, en general amb algunes dades de contacte. El valor per defecte +per a aquesta opció és la versió de live-build utilitzada, la qual cosa pot +ajudar amb la depuració d'errors posterior. La longitud màxima per a aquest +camp és de 128 caràcters. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: Ha de descriure l'editor de la +imatge, en general amb algunes dades de contacte. La longitud màxima per a +aquest camp és de 128 caràcters. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: Això ha d'especificar l'ID de volum +de la imatge. Això s'utilitza com una etiqueta visible per a l'usuari en +algunes plataformes com Windows i Apple Mac OS. La longitud màxima per a +aquest camp és de 32 caràcters. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-contents.ssi new file mode 100644 index 0000000..92d8166 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-contents.ssi @@ -0,0 +1,142 @@ +:B~ Personalització dels continguts + +1~customizing-contents Personalització dels continguts + +Aquest capítol tracta d'afinar la personalització dels continguts del +sistema en viu més enllà de simplement triar els paquets que es desitja +incloure. Els «includes» permeten afegir o reemplaçar fitxers arbitraris en +la imatge en viu, els scripts ganxo (hooks) permeten executar ordres +arbitràries en diferents etapes de la construcció i en el moment d'arrencar, +i la preconfiguració (preseeding) permet configurar els paquets quan +s'instal·len proporcionant respostes a les preguntes de debconf . + +2~includes Includes + +Tot i que l'ideal seria un sistema en viu que inclogués només fitxers +proporcionats per paquets Debian sense modificació, de vegades és convenient +proporcionar o modificar part del contingut a través de fitxers. Amb els +includes, és possible afegir (o substituir) fitxers arbitraris en la imatge +en viu. live-build ofereix dos mecanismes per al seu ús: + +_* Chroot local includes: Aquests permeten afegir o substituir fitxers +dintre de chroot/Live en el sistema de fitxers. Consultar {Live/chroot local +includes}#live-chroot-local-includes per a més informació. + +_* Binary local includes: Aquests permeten afegir o substituir fitxers dins +la imatge binària. Consultar {Binary local includes}#binary-local-includes +per a més informació. + +Consultar {Termes}#terms per a més informació sobre la distinció entre les +imatges "Live" and "binary". + +3~live-chroot-local-includes Live/chroot local includes + +Es poden utilitzar els chroot local includes per a afegir o reemplaçar +fitxers en el sistema de fitxers chroot/Live perquè puguin ser utilitzats en +el sistema en viu. Un ús típic és per a omplir l'esquelet del directori de +l'usuari (#{/etc/skel}#) utilitzat pel sistema en viu per a crear el +directori home de l'usuari en viu. Un altre és el de subministrar fitxers de +configuració que poden ser simplement afegits o reemplaçats en la imatge +sense processar; veure{Live/chroot local hooks}#live-chroot-local-hooks si +es necessita processar-los. + +Per a incloure fitxers, només s'han d'afegir al directori +#{config/includes.chroot}#. Aquest directori es correspon amb el directori +arrel #{/}# del sistema en viu. Per exemple, per a afegir un fitxer +#{/var/www/index.html}# en el sistema en viu, fer: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +La configuració tindrà llavors l'estructura següent: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Els chroot local includes s'instal·len després de la instal·lació del +paquets de tal manera que es sobreescriuen els fitxers instal·lats pels +paquets. + +3~binary-local-includes Binary local includes + +Per a incloure material com documentació o vídeos en el sistema de fitxers +del medi en viu de manera que sigui accessible immediatament després de la +inserció del medi sense haver de arrencar el sistema en viu, es pot +utilitzar els binary local includes. Això funciona de manera similar als +chroot local includes. Per exemple, si els fitxers #{~/video_demo.*}# són +vídeos de demostració del sistema en viu descrits i lligats per una pàgina +d'índex HTML. Només cal copiar el material a #{config/includes.binary/}# de +la següent manera: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +Aquests fitxers apareixeran ara en el directori arrel del medi en viu. + +2~hooks Scripts ganxo (Hooks) + +Els scripts ganxo permeten executar ordres en les etapes de la construcció +chroot i binary per tal de personalitzar la imatge. + +3~live-chroot-local-hooks Live/chroot local hooks + +Per a executar ordres durant l'etapa chroot, crear un script ganxo que +contingui les ordres amb el sufix #{.hook.chroot}# i afegir-lo al directori +#{config/hooks/}#. El ganxo s'executarà en el chroot després que la resta de +la configuració del chroot s'hagi aplicat, assegurar-se que la configuració +inclou tots els paquets i els fitxers que el ganxo necessita per +funcionar. Veure els scripts chroot d'exemple per a diverses tasques comunes +de personalització que es poden trovar a +#{/usr/share/doc/live-build/examples/hooks}# que es poden copiar o fer un +enllaç simbòlic per a utilitzar-los en la pròpia configuració. + +3~boot-time-hooks Scripts ganxo durant l'arrencada + +Per a executar ordres durant l'arrencada, es pot proporcionar scripts ganxo +per a live-config com s'explica a la secció "Personalització" de la seva +pàgina del manual. Es poden afegir els ganxos de live-config a +#{/lib/live/config/}#, tenint en compte la seqüència dels números. A +continuació, afegir el script ganxo propi amb un número de seqüència +apropiat com a prefix, ja sigui com a un chroot local include a +#{config/includes.chroot/lib/live/config/}#, o com un paquet personalitzat +com es va discutir a {Instal·lació de paquets modificats o de +tercers}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +Per a executar ordres durant l'etapa binary, crear un script ganxo que +contingui les ordres amb un sufix #{.hook.binary}# i afegir-lo al directori +#{config/hooks/}#. El ganxo s'executarà després que s'executin totes les +ordres de l'etapa binary però abans dels binary_checksums, la darrera ordre +de l'etapa binary. Les ordres del ganxo no s'executen al chroot, per tant +tenir cura de no modificar cap fitxer de fora del arbre de construcció, o es +pot fer malbé el sistema de construcció! Veure els scripts ganxo binary +d'exemple per a diverses tasques comunes de personalització a +#{/usr/share/doc/live-build/examples/hooks}# que es poden copiar o fer un +enllaç simbòlic per a utilitzar-los en la pròpia configuració. + +2~ Preconfiguració de les preguntes de Debconf + +Els fitxers del directory #{config/preseed/}# amb el sufix #{.cfg}# seguits +del sufix de l'etapa (#{.chroot}# o #{.binary}#) son considerats fitxers de +preconfiguració de debconf i són instal·lats per live-build utilitzant +#{debconf-set-selections}# durant l'etapa corresponent. + +Per a més informació sobre debconf, veure #{debconf(7)}# del paquet +/{debconf}/. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-installer.ssi new file mode 100644 index 0000000..31133ac --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-installer.ssi @@ -0,0 +1,89 @@ +:B~ Personalització de l'instal·lador de debian + +1~customizing-installer Personalització de l'instal·lador de debian + +Les imatges del sistema en viu es poden integrar amb l'instal·lador de +Debian. Hi ha un nombre de diferents tipus d'instal·lació, que varien en el +que s'inclou i en com opera l'instal·lador. + +Tenir en compte l'ús acurat de les lletres majúscules quan es refereix a +"l'instal·lador de Debian" en aquesta secció - quan s'utilitza així ens +referim explícitament a l'instal·lador normal del sistema Debian, i no a una +altra cosa. Es veu sovint abreujat com "d-i". + +2~ Tipus d'instal·lador de Debian + +Els tres principals tipus d'instal·lador són els següents: + +*{Instal·lador de Debian "Normal"}*: Aquesta és una imatge normal de sistema en viu amb un nucli i initrd independents que (quan es seleccionen des del carregador d'arrencada adequat) realitzen una instal·lació estàndard de Debian, igual que si s'hagués descarregat i arrencat una imatge de Debian des d'un CD. Les imatges que contenen un sistema viu i aquest tipus d'instal·lador independent s'anomenen sovint "imatges combinades". + +Amb aquest tipus d'imatges, Debian s'instal·la descarregant i instal·lant +paquets .deb mitjançant /{debootstrap}/, des dels medis locals o alguna +xarxa, aixó resulta en un sistema Debian per defecte instal·lat al disc dur. + +Tot aquest procés pot ser preconfigurat i personalitzadat de moltes formes, +veure les pàgines corresponents al manual de l'instal·lador de Debian per a +més informació. Quan es té un fitxer de preconfiguració que funcioni, +live-build pot posar-lo automàticament a la imatge i activar-lo. + +*{Instal·lador de Debian "Live"}*: Aquesta és una imatge en viu amb un nucli i initrd independents que (quan es seleccionen des del carregador d'arrencada adequat) llancen un instal·lador de Debian. + +La instal·lació continuarà de forma idèntica a l'instal·lació que s'ha +descrit anteriorment, però en la fase d'instal·lació dels paquets, en lloc +d'utilitzar /{debootstrap}/ per a buscar-los i instalar-los, es copia el +sistema de fitxers viu a la destinació. Això s'aconsegueix amb un udeb +especial anomenat live-installer. + +Després d'aquesta etapa, l'instal·lador de Debian continua de forma normal, +instal·lant i configurant elements com ara els gestors d'arrencada i els +usuaris locals, etc + +*{Nota:}* per a donar suport a les entrades de l'instal·lador normal i live en el gestor d'arrencada del mateix medi s'ha de desactivar el live-installer mitjançant la preconfiguració #{live-installer/enable=false}#. + +*{Instal·lador de Debian "d'escriptori"}*: Independentment del tipus d'instal·lador de Debian inclòs, es pot iniciar el #{d-i}# des de l'escriptori fent clic damunt una icona. Aixó és senzill per a l'usuari però perquè funcioni s'ha d'afegir el paquet debian-installer-launcher. + +Tenir en compte que, per defecte, live-build no inclou imatges de +l'instal·lador de Debian en les imatges, ha de ser específicament activat +amb #{lb config}#. A més, tenir en compte que per a que funcioni +l'instal·lador "d'escriptori" el nucli del sistema viu ha de coincidir amb +el nucli que el #{d-i}# utilitza per a l'arquitectura especificada. Per +exemple: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Personalització de l'instal·lador de Debian amb preconfiguració + +Com es descriu en el Manual de l'instal·lador de Debian, a l'apèndix B a +https://www.debian.org/releases/stable/i386/apb.html, "la preconfiguració +proporciona una manera de respondre a les preguntes durant la instal·lació, +sense haver d'introduir les respostes manualment mentre la instal·lació està +en curs. Això permet automatitzar completament la majoria dels tipus +d'instal·lacions i fins i tot ofereix algunes característiques no +disponibles durant les instal·lacions normals." Aquest tipus de +personalització s'aconsegueix millor amb live-build col·locant la +configuració en un fitxer #{preseed.cfg}# a +#{config/includes.installer/}#. Per exemple, per a preconfigurar la variant +local #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Personalitzar el contingut de l'instal·lador de Debian + +Per motius experimentals o de depuració d'errors, és possible que es vulgui +incloure paquets udeb creats localment per al #{d-i}#. Per a afegir-los a la +imatge posar-los a #{config/packages.binary/}#. Es poden incloure fitxers +addicionals o de substitució i alguns directoris a l'initrd de +l'instal·lador d'una manera similar a {Live/chroot local +includes}#live-chroot-local-includes, posant el material a +#{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-overview.ssi new file mode 100644 index 0000000..71200de --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-overview.ssi @@ -0,0 +1,82 @@ +:B~ Personalització dels continguts + +1~customization-overview Visió general de la personalització + +En aquest capítol s'ofereix una visió general de les diverses formes en què +es pot personalitzar un sistema en viu. + +2~ Configuració durant la construcció vs. durant l'arrencada + +La configuració de un sistema en viu es divideix en opcions en temps de +construcció que són les opcions que s'apliquen durant la seva creació i les +opcions d'arrencada del sistema que s'apliquen durant l'arrencada. Les +opcions d'arrencada es divideixen en les què ocorren al principi de +l'arrencada, aplicades pel paquet live-boot, i les que ocorren més tard en +l'arrencada, aplicades per live-config. Qualsevol opció durant l'arrencada +pot ser modificada per l'usuari, especificant-la a l'indicador +d'arrencada. La imatge també pot ser construïda amb els paràmetres +d'arrencada per defecte perquè els usuaris puguin simplement arrencar el +sistema en viu sense especificar cap altra opció, ja que tots els valors per +defecte són adequats. En particular, l'argument #{lb --bootappend-live}# +consta de les opcions de línia d'ordres per defecte del nucli per al sistema +en viu, com ara la persistència, la distribució del teclat o la zona +horària. Veure {Personalització de l'entorn local i el +llenguatge}#customizing-locale-and-language, per exemple. + +Les opcions de configuració durant la construcció es descriuen a la pàgina +del manual de #{lb config}#. Les opcions durant l'arrencada es descriuen a +les pàgines del manual de live-boot i live-config. Malgrat que els paquets +live-boot i live-config s'instal·len en el sistema en viu que s'està +construint, és recomana instal·lar-los en el sistema de construcció per a +tenir una referència fàcil quan s'està treballant en la configuració. És +segur fer-ho, ja que cap dels scripts continguts en ells s'executen a menys +que el sistema s'hagi configurat com a sistema viu. + +2~stages-of-the-build Etapes de la construcció + +El procés de construcció es divideix en etapes, amb personalitzacions +diferentes aplicades successivament en cada una. La primera etapa que +s'executa es la fase *{bootstrap}*. Aquesta és la fase inicial de poblar el +directori chroot amb paquets per a fer un sistema Debian bàsic. Això és +seguit per l'etapa *{chroot}*, que completa la construcció del directori +chroot, omplint-lo amb tots els paquets que s'indiquen en la configuració, +juntament amb qualsevol altre material. La majoria de personalitzacions dels +continguts es produeixen en aquesta etapa. L'etapa final de preparació de la +imatge en viu és l'etapa *{binary}*, quan es construeix una imatge capaç +d'arrencar, amb el contingut del directori chroot per a construir el sistema +de fitxers arrel per al sistema en viu, i que inclou el programa de +instal·lació i qualsevol altre material addicional en el medi de destinació +fora del sistema de fitxers del sistema en viu. Després de construir la +imatge en viu, si està habilitat, s'inclou el codi font original a l'etapa +*{source}*. + +Dins de cadascuna d'aquestes etapes, hi ha una seqüència particular en la +qual s'apliquen les ordres. Això es fa de manera que es garanteixi que les +personalitzacions es poden superposar de manera raonable. Per exemple, dins +l'etapa *{chroot}*, les preconfiguracions (preseeds) s'apliquen abans que +s'instal·lin els paquets, els paquets s'instal·len abans que es copiïn els +fitxers locals, i els ganxos s'executen més tard, després que tots els +materials estiguin al seu lloc. + +2~ Suplementar lb config amb fitxers + +Encara que #{lb config}# crea una configuració en esquelet al directori +#{config/}#, per a aconseguir els objectius, pot ser necessari proporcionar +fitxers addicionals en els subdirectoris de #{config/}#. Depenent d'on +s'emmagatzemen els fitxers en la configuració, poden ser copiats en el +sistema de fitxers del sistema en viu o en el sistema de fitxers de la +imatge binària, o es pot proporcionar configuracions en temps de construcció +del sistema que serien engorroses de passar com opcions de línia +d'ordres. Es pot incloure coses com ara llistes personalitzades de paquets, +art personalitzat o scripts ganxo per a ser executats ja sigui en temps de +construcció o en temps d'arrencada, augmentant la flexibilitat ja +considerable de debian-live amb codi propi. + +2~ Tasques de personalització + +Els següents capítols s'organitzen pel tipus de tasques de personalització +que els usuaris solen realitzar: {Personalització de la instal·lació de +paquets}#customizing-package-installation, {Personalització dels +continguts}#customizing-contents i {Personalització de l'entorn local i el +llenguatge}#customizing-locale-and-language cobreixen només algunes de les +coses que es poden fer. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-packages.ssi new file mode 100644 index 0000000..e904390 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-packages.ssi @@ -0,0 +1,676 @@ +:B~ Personalització de la instal·lació de paquets + +1~customizing-package-installation Personalització de la instal·lació de +paquets + +La personalització més bàsica d'un sistema en viu pot ser la selecció dels +paquets que seran inclosos en la imatge. Aquest capítol explica les diverses +opcions de live-build per a personalitzar la instal·lació de paquets durant +la construcció. Les opcions més importants que influeixen en els paquets que +estan disponibles per a ser instal·lats en la imatge són les àrees de +distribució i el arxiu. Per a garantir velocitats de descàrrega decents, +s'ha de triar un mirall de distribució proper. També es pot incloure +repositoris de backports, paquets experimentals o personalitzats, o incloure +paquets directament com si fossin fitxers. Es poden definir llistes de +paquets, incloent-hi els metapaquets que instal·laran diversos paquets +relacionats alhora, com ara paquets per a un ordinador d'escriptori o un +llenguatge en particular. Finalment, una sèrie d'opcions donen un cert +control sobre /{apt}/ o si es prefereix /{aptitude}/, quan s'instal·len els +paquets durant la construcció. Això pot ser útil si s'utilitza un proxy, es +vol desactivar la instal·lació de paquets recomanats per a estalviar espai, +o hi ha la necessitat de controlar quines versions dels paquets s'instal·len +mitjançant la tècnica pinning d'APT, per nomenar algunes possibilitats. + +2~ Fonts dels paquets + +3~ Distribució, àrees d'arxiu i mode + +La distribució que es tria té una gran importància en els paquets que estan +disponibles per a incloure en una imatge en viu. Només cal especificar el +nom en clau, que per defecte és ${testing} per a la versió ${testing} de +live-build. Qualsevol distribució disponible a l'arxiu pot ser especificada +pel seu nom en clau aquí. (Veure {Termes}#terms per a més detalls.) L'opció +#{--distribution}# no només influeix en l'origen dels paquets dins l'arxiu, +sinó que també instrueix a live-build per a comportar-se segons sigui +necessari per a construir cada distribució suportada. Per exemple, per a +construir la distribució *{unstable}*, sid, s'ha d'especificar: + +code{ + + $ lb config --distribution sid + +}code + +A l'arxiu de la distribució, les àrees són les divisions principals de +l'arxiu. A Debian, es tracta de #{main}#, #{contrib}# i #{non-free}#. Només +#{main}# conté el programari que és part de la distribució Debian, per tant +és el valor per defecte. Es poden especificar un o més valors, per exemple: + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +És dona suport experimental a alguns derivats de Debian a través de l'opció +#{--mode}#. Per defecte, aquesta opció és #{debian}# però només si s'està +construint en un sistema Debian o en un sistema desconegut. Si s'especifica +amb #{lb config}# que es vol construir un dels derivats suportats alehores +es modificaran les opcions per a crear aquest derivat. Si per exemple +s'utilitza #{lb config}# amb el mode #{ubuntu}#, s'utilitzarà el nom de la +distribució i les àrees dels arxius del derivat especificat en lloc dels de +Debian. El «mode» també modifica el comportament de live-build per a +adaptar-lo als derivats. + +*{Nota:}* Els projectes per als quals s'han afegit aquests modes són els principals responsables de donar suport als usuaris d'aquestes opcions. El ${project}, al seu torn, dona suport de desenvolupament només sobre una base de millor esforç, basada en les informacions proporcionades pels projectes derivats ja que nosaltres no desenvolupem ni donem suport a aquests derivats. + +3~ Miralls de distribució + +L'arxiu de Debian es replica a través d'una àmplia xarxa de miralls a tot el +món perquè la gent de cada regió pugui triar un mirall proper amb la millor +velocitat de descàrrega. Cadascuna de les opcions #{--mirror-*}# governa +quin mirall de distribució s'utilitzarà en les diverses etapes de la +construcció. Recordar de {Etapes de la construcció}#stages-of-the-build que +l'etapa *{bootstrap}* es quan el chroot s'omple inicialment per +/{debootstrap}/ amb un sistema mínim i l'etapa *{chroot}* és quan +s'utilitza el chroot per a la construcció del sistema de fitxers del sistema +en viu. D'aquesta manera, s'utilitzen els miralls corresponents per a +aquestes etapes, i més tard, durant l'etapa *{binary}* s'utilitzen els +valors #{--mirror-binary}# i #{--mirror-binary-security}# substituint +qualsevol mirall utilitzat en una etapa anterior. + +3~distribution-mirrors-build-time Miralls de distribució utilitzats en temps +de construcció + +Per a establir els miralls de la distrubució utilitzats en temps de +construcció perquè apuntin a una rèplica local, és suficient establir +#{--mirror-bootstrap}# i #{--mirror-chroot-security}# de la manera següent. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +El mirall per al chroot, especificat per l'opció #{--mirror-chroot}#, per +defecte pren el mateix valor que #{--mirror-bootstrap}# + +3~ Miralls de distribució utilitzats en temps d'execució + +Les opcions #{--mirror-binary*}# governen els miralls de distribució que +acaben a la imatge binària. Aquestes poden ser utilitzades per a instal·lar +paquets addicionals mentre s'executa el sistema en viu. Els valors per +defecte fan servir #{httpredir.debian.org}#, un servei que tria un mirall +geogràficament a prop en funció, entre altres coses, de la familia de la IP +de l'usuari i de la disponibilitat del mirall. Aquesta és una opció adequada +quan no es pot predir quin serà el millor mirall per a tots els usuaris. O +es pot especificar els valors propis com es mostra en l'exemple següent. Una +imatge construïda a partir d'aquesta configuració només seria convenient per +als usuaris en una xarxa on "#{mirror}#" és abastable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Repositoris addicionals + +És possible afegir més repositoris, ampliant les opcions de paquets més +enllà dels disponibles en la pròpia distribució de destinació. Aquests poden +ser, per exemple, per a backports, experimentals o paquets +personalitzats. Per a configurar repositoris addicionals, crear els fitxers +#{config/archives/your-repository.list.chroot}#, i/o +#{config/archives/your-repository.list.binary}#. Igual que amb les opcions +#{--mirror-*}# aquest regeix els repositoris utilitzats en l'étapa +*{chroot}* durant la construcció de la imatge, i a l'étapa *{binary}*, és a +dir, per a ser utilitzades quan s'executa el sistema en viu. + +Per exemple, #{config/archives/live.list.chroot}# permet instal·lar paquets +des del repositori d'instantànies de debian-live en el moment de construcció +del sistema viu. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +Si s'afegeix la mateixa línia a #{config/archives/live.list.binary}#, el +repositori sera afegit al directori #{/etc/apt/sources.list.d/}# del sistema +viu. + +Si aquests fitxers existeixen, són utilitzats de forma automàtica. + +També s'ha de posar la clau GPG utilitzada per a signar el repositori en +fitxers #{config/archives/your-repository.key.{binary,chroot}}#. + +En cas de necessitar un APT pinning personalitzat, es poden col·locar les +preferències APT en fitxers +#{config/archives/your-repository.pref.{binary,chroot}}#, que seran afegits +automàticament al sistema en viu al directori #{/etc/apt/preferences.d/}#. + +2~choosing-packages-to-install Selecció dels paquets a instal·lar + +Hi ha una sèrie de formes de triar els paquets que live-build instal·larà en +la imatge, que abasta una varietat de necessitats diferents. Es pot +simplement anomenar paquets individualment per a instal·lar en una llista de +paquets. També es pot optar per utilitzar metapaquets a les llistes, o +seleccionar-los utilitzant camps de control de fitxers de paquets. I, +finalment, es poden copiar paquets com si fossin fitxers dins del arbre +#{config/}#, que és un mètode que s'adapta perfectament a fer proves amb +paquets nous o experimentals abans de afegirlos a un repositori. + +3~package-lists Llistes de paquets + +Les llistes de paquets són una forma eficaç d'expressar quins paquets han de +ser instal·lats. La sintaxi de la llista suporta seccions condicionals que +fa que sigui fàcil construir llistes i adaptar-les per al propi ús en +múltiples configuracions. Els noms dels paquets també poden ser injectats a +la llista amb ajudants de l'intèrpret d'ordres en temps de construcció. + +*{Nota:}* El comportament de live-build a l'hora d'especificar un paquet que no existeix està determinat per la elecció que es faci de l'eina APT. Veure {Elegir apt or aptitude}#choosing-apt-or-aptitude per a més detalls. + +3~using-metapackages Ús dels metapaquets + +La forma més senzilla per a omplir la llista de paquets és utilitzar una +tasca metapaquet mantinguda per una distribució. Per exemple: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +Això reemplaça l'antic mètode de llistes predefinides de #{live-build}# +2.x. A diferència de les llistes predefinides, els metapaquets no són +específics del projecte Live Systems. Per contra, són mantinguts per grups +d'especialistes que treballen dins la distribució i per tant, reflecteixen +el consens de cada grup sobre els paquets que serviran millor a les +necessitats dels usuaris. A més, abasten una gamma molt més àmplia de casos +d'ús que les llistes predefinides que substitueixen. + +Tots els metapaquets tenen el prefix #{task-}#, de manera que una forma +ràpida de determinar quins estan disponibles (encara que pot contenir un +grapat d'entrades falses que coincideixin amb el nom, però que no són +metapaquets) és fer coincidir el nom del paquet amb: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +A més d'aquests, es troben altres metapaquets amb diverses +finalitats. Alguns són subconjunts de paquets de tasques més àmplies, com +#{gnome-core}#, mentre que altres són parts individuals especialitzades de +un Debian Pure Blend, com els metapaquets #{education-*}#. Per a obtenir una +llista de tots els metapaquets que hi ha a l'arxiu, instal·lar el paquet +#{debtags}# i llistar tots els paquets amb l'etiqueta #{role::metapackage}# +de la següent manera: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Llistes locals de paquets + +Ja sigui afegint metapaquets a una llista, paquets individuals, o una +combinació d'ambdós, totes les llistes de paquets locals s'emmagatzemen a +#{config/package-lists/}#. Es pot utilitzar més d'una llista i això es +presta molt bé als dissenys modulars. Per exemple, es pot decidir dedicar +una llista a una elecció particular d'escriptori, l'altra a una col·lecció +de paquets relacionats que puguin ser fàcilment utilitzats al damunt d'un +escriptori diferent. Això permet experimentar amb diferents combinacions de +conjunts de paquets amb un mínim d'esforç, intercanviant llistes comunes +entre els diferents projectes d'imatges en viu. + +Les llistes de paquets que es troben en aquest directori han de tenir el +sufix #{.list}# per a ser processades, i a més a més un sufix d'etapa +adicional #{.chroot}# o #{.binary}# per a indicar per a quina etapa és la +llista. + +*{Nota:}* Si no s'especifica el sufix d'etapa, la llista s'utilitzarà per a ambdues etapes. Normalment, s'especifica #{.list.chroot}# de manera que els paquets només s'instal·laran al sistema de fitxers en viu i no hi haura una còpia extra del #{.deb}# en el medi. + +3~ Llistes locals de paquets per a l'etapa binary + +Per a crear una llista per a l'etapa binary, crear un fitxer amb el sufix +#{.list.binary}# a #{config/package-lists/}#. Aquests paquets no +s'instal·len al sistema de fitxers en viu però s'inclouen en el medi en viu +al directori #{pool/}#. Un ús típic d'aquesta llista seria amb una de les +variants del instal·lador non-live. Com s'ha esmentat anteriorment, si es +vol que aquesta llista sigui la mateixa que la llista de l'etapa chroot, +simplement utilitzar el sufix #{.list}#. + +3~generated-package-lists Generar llistes de paquets + +De vegades passa que la millor manera de crear una llista és generar-la amb +un script. Qualsevol línia que comença amb un signe d'exclamació indica una +ordre que s'executarà dins del chroot quan la imatge es construeix. Per +exemple, es podria incloure la línia #{! grep-aptavail -n -sPackage +-FPriority standard | sort}# en una llista de paquets per a produir una +llista ordenada de paquets disponibles amb #{Priority: standard}#. + +De fet, la selecció de paquets amb l'ordre #{grep-aptavail}# (del paquet +#{dctrl-tools}#) és tan útil que #{live-build}# proporciona un script +#{Packages}# d'ajuda per motius de comoditat. Aquest script accepta dos +arguments: #{field}# i #{pattern}#. Per tant, es pot crear una llista amb +els següents continguts: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Ús de condicionals dins de les llistes de paquets + +Qualsevol de les variables de configuració de live-build emmagatzemades a +#{config/*}# (menys el prefix #{LB_}#) poden ser utilitzades en sentències +condicionals en les llistes de paquets. En general, això significa qualsevol +opció #{lb config}# en lletres majuscules i amb guions canviats a guions +baixos. Però a la pràctica, només tenen sentit les que influeixen en la +selecció de paquets, com ara #{DISTRIBUTION}#, #{ARCHITECTURES}# o +#{ARCHIVE_AREAS}#. + +Per exemple, per a instal·lar #{ia32-libs}# si s'especifica +#{--architectures amd64}#: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +És possible fer un test d'un nombre de valors, per exemple per a instal·lar +/{memtest86+}/ si s'especifica #{--architectures i386}# o #{--architectures +amd64}#: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +També es pot provar amb variables que poden contenir més d'un valor, per +exemple, per a instal·lar /{vrms}/ si s'especifica o #{contrib}# o +#{non-free}# a través de l'opció #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +No és possible el anidament dels condicionals. + +% FIXME: + +3~ Eliminar paquets durant la instal·lació + +Es pot crear llistes de paquets en fitxers amb els sufixos +#{.list.chroot_live}# i #{.list.chroot_install}# dins del directori +#{config/package-lists}#. Si hi ha una llista «live» i una llista «install» +els paquets de la llista #{.list.chroot_live}# s'eliminaran amb un script +ganxo després de la instal·lació (si l'usuari utilitza l'instal·lador). Els +paquets de la llista #{.list.chroot_install}# seran presents tant en el +sistema en viu com en el sistema instal·lat. Aquest és un cas especial per +al programa d'instal·lació i pot ser útil si es té #{--debian-installer +live}# establert en la configuració i es desitja eliminar paquets específics +del sistema en viu durant la instal·lació. + +3~desktop-and-language-tasks Tasques d'escriptori i llenguatge + +Les tasques d'escriptori i el llenguatge són casos especials que necessiten +una mica de planificació i configuració extra. Les imatges en viu són +diferentes de les imatges de l'instal·lador de Debian en aquest sentit. A +l'instal·lador de Debian, si el medi es va preparar per a obtenir un tipus +d'entorn d'escriptori en particular, la tasca corresponent s'instal·larà +automàticament. Per tant hi ha tasques internes #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# i #{xfce-desktop}#, cap de les quals +s'ofereixen al menú de #{tasksel}#. De la mateixa manera, no hi ha cap +entrada de menú per a tasques de llengües, però l'elecció del idioma de +l'usuari durant la instal·lació influeix en la selecció de les tasques de +les llengües corresponents. + +En el desenvolupament d'una imatge en viu d'escriptori, la imatge sol +arrencar directament a un escriptori de treball, les opcions d'escriptori i +de llengua han estat fetes en temps de construcció, no en temps d'execució +com en el cas del instal·lador de Debian. Això no vol dir que una imatge en +viu no es pugui construir per a donar suport a diversos equips d'escriptori +o diversos idiomes i oferir a l'usuari una opció, però això no és el +comportament de live-build per defecte. + +Com que no hi ha cap ajust automàtic per a les tasques de llengua que +incloguin coses com ara tipus de lletres específics per a una llengua o +paquets de mètode d'entrada, si es vol, cal especificar-ho en la +configuració. Per exemple, una imatge d'escriptori GNOME que contingui +suport per al alemany podrie incloure les següents tasques metapaquets: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Tipus i versió del nucli + +Depenent de l'arquitectura, s'inclouran per defecte en la imatge un o més +tipus de nuclis. Es pot triar diferents tipus a través de l'opció +#{--linux-flavours}#. Cada tipus té un sufix per a l'arrel per defecte +#{linux-image}# per a formar el nom de cada metapaquet que al seu torn depèn +d'un paquet del nucli exacte que s'ha d'incloure en la imatge. + +Així, per defecte, una imatge per a l'arquitectura #{amd64}# inclourà el +metapaquet #{linux-image-amd64}# i una imatge per a l'arquitectura #{i386}# +inclourà el metapaquet #{linux-image-586}#. + +Quan hi ha més d'una versió del paquet del nucli disponible en els arxius +configurats, es pot especificar el nom d'un paquet del nucli amb l'opció +#{--linux-packages}#. Per exemple, suposem que s'està construint una imatge +d'arquitectura #{amd64}# i es vol afegir l'arxiu experimental amb propòsits +de fer proves. Perquè es pugui instal·lar el nucli +#{linux-image-3.18.0-trunk-amd64}# es podria configurar la imatge de la +següent manera: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Nuclis personalitzats + +Es pot construir i incloure nuclis propis personalitzats, sempre que +s'integrin en el sistema de gestió de paquets de Debian. El sistema de +live-build no és compatible amb nuclis no construïts com paquets #{.deb}#. + +La manera apropiada i recomanable d'implementar els propis paquets del nucli +és seguir les instruccions del #{kernel-handbook}#. Recordar que s'ha de +modificar l'ABI i els sufixos del tipus apropiadament, i a continuació, +incloure un conjunt complet dels packets que corresponen amb #{linux}# i +#{linux-latest}# al repositori. + +Si s'opta per construir els paquets del nucli sense els metapaquets a joc, +cal especificar una arrel #{--linux-packages}# apropiada com s'indica a +{Tipus i versió del nucli}#kernel-flavour-and-version. Com expliquem a +{Instal·lació de paquets modificats o de +tercers}#installing-modified-or-third-party-packages, és millor si +s'inclouen els paquets del nucli personalitzat en un repositori propi, tot i +que les alternatives discutides en aquella secció també funcionen. + +Està més enllà de l'abast d'aquest document donar consells sobre com +personalitzar un nucli. No obstant això, cal, almenys, assegurar-se que la +configuració compleix els següents requisits mínims: + +_* Utilitzar una ramdisk inicial. + +_* Incloure el mòdul d'unió del sistema de fitxers (normalment #{aufs}#). + +_* Incloure tots els mòduls del sistema d'arxius requerits per la +configuració (normalment #{squashfs}#). + +2~installing-modified-or-third-party-packages Instal·lació de paquets +modificats o de tercers + +Si bé està en contra de la filosofia d'un sistema en viu, de vegades pot ser +necessària la construcció d'un sistema amb versions modificades dels paquets +que es troben al arxiu de Debian. Pot ser per a modificar o donar suport a +funcions addicionals, les llengües o les marques, o fins i tot per a +eliminar elements dels paquets existents que són indesitjables. De la +mateixa manera, es poden utilitzar paquets de tercers per a afegir alguna +funcionalitat personalitzada i/o propietària. + +Aquesta secció no cobreix l'assessorament en matèria de construcció o +manteniment de paquets modificats. Però el métode de Joachim Breitner's 'How +to fork privately' a +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +pot ser d'interès. La creació de paquets personalitzats es tracta a Debian +New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ i en +altres llocs. + +Hi ha dues formes d'instal·lar paquets personalitzats modificats: + +_* #{packages.chroot}# + +_* L'ús d'un repositori APT personalitzat + +Utilitzar #{packages.chroot}# és més fàcil d'aconseguir i útil per a +personalitzacions "ràpides", però té una sèrie d'inconvenients, mentre que +l'ús d'un repositori APT personalitzat és més costós en la quantitat de +temps necessari per a posar-lo en marxa. + +3~ Fer servir #{packages.chroot}# per a instaŀar paquets personalitzats + +Per a instaŀar un paquet personalitzat, només s'ha de copiar al directori +#{config/packages.chroot/}#. Els paquets que es troben dins d'aquest +directori s'instal·laran automàticament en el sistema en viu durant la +construcció - no cal especificar res més en cap altre lloc. + +Els paquets *{han de}* ser nomenats en la forma prescrita. Una manera simple +de fer això és utilitzar #{dpkg-name}#. + +Utilitzar #{packages.chroot}# per a la instal·lació de paquets +personalitzats té els seus desavantatges: + +_* No és possible utilitzar APT segur. + +_* Cal posar tots els paquets apropiats al directori +#{config/packages.chroot/}#. + +_* No es adient per a l'emmagatzematge de configuracions de sistemes en viu +en el control de revisió. + +3~ Fer servir un repositori APT per a instal·lar paquets personalitzats + +A diferència de #{packages.chroot}#, quan s'utilitza un repositori APT +personalitzat s'ha d'assegurar que s'especifiquen els paquets en un altre +lloc. Veure {Selecció dels paquets a +instal·lar}#choosing-packages-to-install per a més detalls. + +Si bé crear un repositori APT per a instal·lar paquets personalitzats pot +semblar un esforç innecessari, la infraestructura pot ser fàcilment +reutilitzada en una data posterior per a oferir actualitzacions dels paquets +modificats. + +3~ Paquets personalitzats i APT + +live-build utilitza APT per a instal·lar tots els paquets al sistema en viu, +per tant, heretarà els comportaments d'aquest programa. Un exemple rellevant +és que (assumint una configuració per defecte) si es dóna el cas que un +paquet està disponible en dos repositoris diferents, amb diferents números +de versió, APT triarà per a instal·lar el paquet amb la versió més alta. + +A causa d'això, s'aconsella augmentar el nombre de la versió dels paquets +personalitzats als fixers #{debian/changelog}# per a assegurar-se que la +versió modificada és la que s'instal·la en lloc d'una dels repositoris +oficials de Debian. Això també es pot aconseguir mitjançant l'alteració de +les preferències d'APT del sistema en viu - veure {APT pinning}#apt-pinning +per a més informació. + +2~ Configurar APT en temps de construcció + +Es pot configurar APT a través d'una sèrie d'opcions que només s'apliquen en +temps de construcció. (La configuració d'APT al sistema en funcionament en +viu es pot fer de forma normal per als continguts del sistema en viu, és a +dir, mitjançant la inclusió de les configuracions adequades a través de +#{config/includes.chroot/}#.) Per a obtenir una llista completa, buscar les +opcions que comencen amb #{apt}# a la pàgina del manual de #{lb_config}#. + +3~choosing-apt-or-aptitude Elegir apt o aptitude + +Es pot optar per utilitzar /{apt}/ o /{aptitude}/ a l'hora d'instal·lar +paquets en temps de construcció. Quina utilitat s'usa es configura gràcies +al argument #{--apt}# de #{lb config}#. Escollir el mètode d'implementació +per al comportament preferit durant la instal·lació de paquets, la +diferència notable és la forma en que es manegen els paquets que falten. + +_* #{apt}#: Amb aquest mètode, si un paquet que s'especifica falta, +l'instal·lació de paquets fallarà. Aquesta és la configuració per defecte. + +_* #{aptitude}#: Amb aquest mètode, si s'especifica un paquet que falta, +l'instal·lació de paquets tindrà èxit. + +3~ L'ús d'un proxy amb APT + +Una configuració típica d'APT és per a fer front a la construcció d'una +imatge darrere d'un proxy. Es pot especificar el proxy per a APT amb les +opcions #{--apt-ftp-proxy}# o #{--apt-http-proxy}# segons sigui necessari, +per exemple, + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Afinar APT per a estalviar espai + +Pot ser necessari estalviar espai en el medi destinat a la imatge, en aquest +cas una o altra o ambdós de les següentes opcions poden ser d'interès. + +Si no es vol incloure els índexs d'APT en la imatge, es poden omitir amb: + +code{ + + $ lb config --apt-indices false + +}code + +Això no influirà en les entrades de #{/etc/apt/sources.list}#, sinó +simplement si #{/var/lib/apt}# conté els fitxers dels índexs o no. El +desavantatge és que APT necessita aquests índexs per tal d'operar en el +sistema en viu, així que abans d'executar per exemple #{apt-cache search}# o +#{apt-get install}#, l'usuari primer ha fer un #{apt-get update}# per a +crear aquests índexs. + +Si es considera que la instal·lació de tots els paquets recomanats infla +massa la imatge, sempre que s'estigui preparat per a fer front a les +conseqüències que s'analitzen a continuació, es pot desactivar aquesta opció +per defecte d'APT amb: + +code{ + + $ lb config --apt-recommends false + +}code + +La conseqüència més important de desactivar els «recommends» és que +#{live-boot}# i #{live-config}# recomanen alguns paquets que proporcionen +una funcionalitat important utilitzada per la majoria de configuracions +Live, com per exemple #{user-setup}# recomanat per #{live-config}# i que +s'utilitza per a crear l'usuari en viu. En tots menys en els casos més +excepcionals es necessita tornar a afexir almenys alguns dels recommends a +les llistes de paquets o en cas contrari la imatge no funcionarà com +s'espera, si és que funciona. Mirar els paquets recomanats per a cada un +dels paquets inclosos en la construcció i si no s'està segur que es poden +ometre, tornar a afegir-los a les llistes de paquets. + +La conseqüència més general aquí és que si no s'instal·len els paquets +recomanats per un paquet determinat, és a dir, "els paquets que es troben +junts amb aquest en totes les instal·lacions a menys que siguin inusuals" +(Debian Policy Manual, secció 7.2), alguns paquets que en realitat són +necessaris per als usuaris del sistema Live poden ser omesos. Per tant, +suggerim revisar la diferència que desactivar els paquets recomanats té en +la llista de paquets (veure el fitxer #{binary.packages}# generat per #{lb +build}#) i tornar a incloure a la llista els paquets que falten que haurien +de ser instal·lats. Si només es vol deixar de banda un petit nombre de +paquets recomanats, es pot deixar els «recommends» activats i establir una +prioritat pin d'APT negativa en els paquets seleccionats per a impedir la +seva instal·lació, com s'explica a {APT pinning}#apt-pinning. + +3~ Passar opcions per a apt o aptitude + +Si no hi ha cap opció #{lb config}# per a modificar el comportament d'APT de +la manera què es necessita, es pot utilitzar #{--apt-options}# o +#{--aptitude-options}# per a passar opcions a l'eina APT +configurada. Consultar les pàgines dels manual #{apt}# i #{aptitude}# per a +més detalls. Tenir en compte que ambdues opcions tenen valors per defecte +que s'hauran de mantenir, a més de les opcions que es proporcionen. Així, +per exemple, suposant que s'ha inclòs algun paquet de +#{snapshot.debian.org}# per a fer proves i es vol especificar +#{Acquire::Check-Valid-Until=false}# perquè APT no es queixe de que el +fitxer #{Release}# ja ha caducat es podria fer com en el exemple següent, +afegint la nova opció després del valor per defecte #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Consultar les págines del manual per a entendre completament aquestes +opcions i quan utilitzar-les. Això és només un exemple i no s'ha +d'interpretar com un consell per a configurar la imatge. Aquesta opció no +seria adequada, per exemple, per a una versió final d'una imatge en viu. + +Per a configuracions més complicades que impliquen opcions #{apt.conf}# pot +ser adequat crear un fitxer #{config/apt/apt.conf}#. Consultar també les +altres opcions #{apt-*}# per a tenir algunes dreceres convenients per a les +opcions que es necessiten amb freqüència. + +3~apt-pinning APT pinning + +Com a referència, llegir primer la pàgina del manual +#{apt_preferences(5)}#. Es pot configurar APT pinning durant la construcció, +o bé durant l'execució. En el primer cas, crear #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, i #{config/apt/preferences}#. Per al +segon cas, crear #{config/includes.chroot/etc/apt/preferences}#. + +Suposem que s'està construint un sistema en viu ${testing} però es necessita +que tots els paquets «live-» que acaben dins de la imatge binària +s'instal·lin desde sid en temps de construcció. Cal afegir sid a les fonts +d'APT i fer un pin dels paquets live amb una prioritat més alta, però tots +els altres paquets amb una prioritat més baixa que la prioritat per defecte +de manera que només els paquets que es vol s'instal·lin desde sid en el +moment de la construcció i tots els altres es prenguin de la distribució de +destinació, ${testing}. Això es pot aconseguir de la manera següent: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Una prioritat pin negativa evitarà que un paquet s'instal·li, com en el cas +que no es vulgui un paquet que és recomanat per un altre paquet. Suposem que +s'està construint una imatge LXDE afegint #{task-lxde-desktop}# a +#{config/package-lists/desktop.list.chroot}# però no es desitja que al +usuari se li demani que guardi les contrasenyes wifi al keyring. Aquesta +llista depèn de /{lxde-core}/, que recomana /{gksu}/, que al seu torn +recomana /{gnome-keyring}/. Si es vol omitir el paquet recomanat +/{gnome-keyring}/, es pot fer mitjançant l'addició de les següents línies a +#{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-runtime.ssi new file mode 100644 index 0000000..de3d9a5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_customization-runtime.ssi @@ -0,0 +1,468 @@ +:B~ Personalització dels comportaments en temps d'execució + +1~customizing-run-time-behaviours Personalització dels comportaments en +temps d'execució + +Tota la configuració que es fa durant l'execució es feta per +live-config. Aquestes són algunes de les opcions més comunes de live-config +en que els usuaris estan interessats. Una llista completa de totes les +possibilitats es poden trobar a la pàgina del manual de live-config. + +2~ Personalitzar l'usuari en viu + +Una consideració important és que l'usuari en viu es creat per live-boot +durant l'arrencada i no per live-build en temps de construcció. Això +influeix no només en on s'han de introduir els materials relacionats amb +l'usuari durant la construcció, tal i com es va explicar a {Live/chroot +local includes}#live-chroot-local-includes, sinó també en els grups i els +permisos associats amb l'usuari. + +Es poden especificar grups addicionals als que pertanyerà l'usuari en viu +mitjançant l'ús de qualsevol de les possibilitats de configuraciò de +live-config. Per exemple, per a afegir l'usuari en viu al grup #{fuse}#, es +pot afegir el següent fitxer a +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +o utilitzar +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +com paràmetre d'arrencada. + +També és possible canviar el nom de l'usuari per defecte "user" i la +contrasenya per defecte "live". Si es vol fer això per alguna raó, es pot +aconseguir fàcilment de la següent manera: + +Per a canviar el nom de l'usuari per defecte només s'ha d'especificar en la +configuració: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +Una forma possible de canviar la contrasenya per defecte és per mitjà d'un +ganxo com s'explica a {Scripts ganxo durant +l'arrencada}#boot-time-hooks. Per a fer això, es pot utilitzar el script +ganxo "passwd" de #{/usr/share/doc/live-config/examples/hooks}#, posar-li un +prefix adequat (per exemple 2000-passwd) i afegir-lo a +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Personalització de l'entorn local i el +llenguatge + +Quan el sistema en viu arrenca, el llenguatge està implicat en dos passos: + +_* la generació de locales + +_* establir la configuració del teclat + +La configuració local per defecte en la construcció d'un sistema viu és +#{locales=en_US.UTF-8}#. Per a definir la locale que s'ha de generar, +utilitzar el paràmetre #{locales}# de la opció #{--bootappend-live}# de #{lb +config}#, per exemple. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Es poden especificar diverses locales en una llista separada per comes. + +Aquest paràmetre, així com els paràmetres de configuració del teclat que +s'indiquen a continuació, també es pot utilitzar en la línia d'ordres del +nucli. Es pot especificar una configuració regional mitjançant +#{language_country}# (en aquest cas s'utilitza la codificació per defecte) o +la forma completa #{language_country.encoding}#. Una llista de locales +suportades i la codificació per a cadascuna es poden trobar a +#{/usr/share/i18n/SUPPORTED}#. + +#{live-config}# s'encarrega de la configuració del teclat per a X i per a la +consola utilitzant el paquet #{console-setup}#. Per a la seva configuració +es pot fer servir els paràmetres d'arrencada #{keyboard-layouts}#, +#{keyboard-variants}#, #{keyboard-options}# i #{keyboard-model}# mitjançant +l'opció #{--bootappend-live}#. Es poden trobar opcions vàlides per a aquests +a #{/usr/share/X11/xkb/rules/base.lst}#. Per a trobar distribucions de +teclat i variants per a un idioma determinat, s'ha d'intentar cercar el nom +en anglès de la llengua i/o el país on es parla l'idioma, per exemple: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Tinir en compte que cada variant mostra la distribució que s'aplica en la +descripció. + +Sovint, només la distribució necessita ser configurada. Per exemple, per a +obtenir els fitxers de configuració regional per a la distribució del teclat +alemany i suís-alemany per a l'entorn gràfic X: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +No obstant això, per als casos d'ús molt específics, potser es vol incloure +altres paràmetres. Per exemple, per a establir un sistema francès, amb una +distribució de teclat French-Dvorak (anomenat Bepo) en un teclat USB +TypeMatrix EZ-Reach 2030, utilitzar: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Es poden especificar diversos valors per a cada una de les opcions +#{keyboard-*}# en una llista separada per comes amb l'excepció de +#{keyboard-model}#, que només accepta un valor. Veure la pàgina del manual +#{keyboard(5)}# per a més detalls i exemples de les variables #{XKBMODEL}#, +#{XKBLAYOUT}#, #{XKBVARIANT}# i #{XKBOPTIONS}#. Si s'especifiquen diversos +valors de #{keyboard-variants}# es correspondran un a un amb els valors +#{keyboard-layouts}# (veure #{setxkbmap(1)}# opció #{-variant}#). Es poden +utilitzar valors buits, per exemple, per a definir dos dissenys, el valor +predeterminat US QWERTY i l'altre US Dvorak: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistència + +Un paradigma d'un live cd és ser un sistema pre-instal·lat, que arrenca +desde medis de només lectura, com un cdrom, on les modificacions no +sobreviuen als reinicis del maquinari que l'executa. + +Un sistema en viu és una generalització d'aquest paradigma i per tant, +compatible amb altres medis, a més dels CDs, però tot i així, en el seu +comportament per defecte, s'ha de considerar de només lectura i totes les +evolucions en temps d'execució del sistema es perden al apagar l'equip. + +La "Persistència" és un nom comú per a nomenar els diferents tipus de +solucions per a guardar després de reiniciar algunes, o totes, les dades +d'aquesta evolució en temps d'execució del sistema. Per a entendre com +funciona, seria útil saber que, encara que el sistema s'inicia i s'executa +des de medis de només lectura, les modificacions als fitxers i directoris +s'escriuen ens medis d'escriptura, en general un ramdisk (tmpfs) i les dades +dels discos ram no sobreviuen als reinicis. + +Les dades emmagatzemades en aquest disc ram han de ser guardades en un +suport d'escriptura persistent com medis d'emmagatzematge locals, un recurs +compartit de xarxa o fins i tot una sessió d'una multisessió de un CD/DVD +(re)grabable. Tots aquests medis són compatibles amb el sistemes en viu de +diferents maneres, i tots menys l'últim, requereixen un paràmetre especial +que s'especifica en l'arrencada: #{persistence}#. + +Si s'utilitza el paràmetre d'arrencada #{persistence}# (i no s'utilitza +#{nopersistence}#) es proven els medis locals d'emmagatzematge (per exemple, +discs durs, unitats USB) buscant volums amb persistència durant +l'arrencada. És possible restringir els tipus de volums amb persistència que +s'utilitzarà mitjançant l'especificació de certs paràmetres d'arrencada que +es descriuen a la pàgina del manual de live-boot(7). Un volum amb +persistència és qualsevol dels següents: + +_* una partició, identificada pel seu nom GPT. + +_* un sistema de fitxers, identificat per la seva etiqueta de sistema de +fitxers. + +_* un fitxer imatge situat en l'arrel de qualsevol sistema de fitxers +llegibles (fins i tot una partició NTFS d'un altre SO), identificat pel seu +nom de fitxer. + +L'etiqueta de volum per als overlays ha de ser #{persistence}# però serà +passat per alt a menys que contingui un fitxer anomenat #{persistence.conf}# +que s'utilitza per a personalitzar completament la persistència del volum, +és a dir, especificar els directoris que es volen conservar en el volum de +persistència després de reiniciar. Veure {El fitxer +persistence.conf}#persistence-conf per a més detalls. + +Aquests són alguns exemples de com preparar un volum que s'utilitzarà per a +la persistència. Pot ser, per exemple, una partició ext4 en un disc dur o en +una clau USB creat amb, per exemple: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +Veure també {Utilitzar l'espai lliure en una memòria +USB}#using-usb-extra-space. + +Si ja hi ha una partició al dispositiu, és pot canviar l'etiqueta amb un +dels següents: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Heus aquí un exemple de com crear un fitxer imatge basat en ext4 per a ser +utilitzat per a la persistència: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Un cop s'ha creat el fitxer imatge, per exemple, per a fer #{/usr}# +persistent però només guardant els canvis que es fan en aquest directori i +no tots els continguts de #{/usr}#, es pot utilitzar l'opció "union". Si el +fitxer imatge es troba en el directori home, copiar-lo a l'arrel del sistema +de fitxers del disc dur i muntar-lo a #{/mnt}# de la següent manera: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +A continuació, crear el fitxer #{persistence.conf}# afegint contingut i +desmuntar el fitxer imatge. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Ara, reiniciar el sistema i arrencar el medi en viu amb el paràmetre +d'arrencada "persistence". + +3~persistence-conf El fitxer persistence.conf + +Un volum amb l'etiqueta #{persistence}# ha de ser configurat mitjançant un +fitxer #{persistence.conf}# per a fer directoris arbitraris +persistents. Aquest fitxer, ubicat a l'arrel del sistema de fitxers del +volum, controla els directoris que fa persistents, i de quina manera. + +A la pàgina del manual de persistence.conf(5) s'explica en detall com es +configuran els muntatges de les overlays, però un simple exemple hauria de +ser suficient per a la majoria d'usos. Si es vol fer el directori home i el +directori del cache d'APT persistents en un sistema de fitxers ext4 a la +partició /dev/sdb1: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Després es reinicia el sistema. Durant la primera arrencada els continguts +de #{/home}# i #{/var/cache/apt}# es copiaran en el volum de la +persistència, i d'aquí en endavant tots els canvis en aquests directoris es +guardaran en aquest volum. Tenir en compte que les rutes que apareixen en el +fitxer #{persistence.conf}# no poden contenir espais en blanc o els +components especials #{.}# i #{..}#. A més, ni #{/lib}#, #{/lib/live}# (o +qualsevol dels seus subdirectoris) ni #{/}# es poden fer persistents +utilitzant muntatges personalitzats. Com a solució per a aquesta limitació +es pot afegir #{/ union}# al fitxer #{persistence.conf}# per a aconseguir +una persistència completa. + +3~ Utilitzar diversos medis persistents + +Hi ha diferents mètodes per utilitzar múltiples volums de persistència per a +diferents casos d'ús. Per exemple, utilitzar diversos volums al mateix temps +o seleccionar-ne només un, entre varis, per a fins molt específics. + +Es poden utilitzar diversos volums diferents de muntatges personalitzats +(amb els seus propis fitxers #{persistence.conf}# però si diversos volums +fan que el mateix directori sigui persistent, només s'utilitzarà un +d'ells. Si qualsevol dels dos muntatges són "imbricats" (és a dir, un és un +sub-directori de l'altre) el directori pare es muntarà abans que el +directori fill per a evitar que amb el muntatge un directori no sigui +ocultat per l'altre. Els muntatges personalitzats imbricats són problemàtics +si estan enumerats en el mateix fitxer #{persistence.conf}#. Veure la pàgina +del manual persistence.conf(5) per a saber com manejar aquest cas, si +realment es necessita (una pista: en general no cal fer-ho). + +Un possible cas d'ús: Per a guardar les dades de l'usuari, és a dir +#{/home}# i les dades del superusuari, és a dir #{/root}# en diferents +particions, crear dues particions amb l'etiqueta #{persistence}# i afegir un +fitxer #{persistence.conf}# en cadascuna d'aquesta manera #{# echo "/home" > +persistence.conf}# per a la primera partició que guardarà els fitxers de +l'usuari i #{# echo "/root" > persistence.conf}# per a la segona partició +que emmagatzemarà els fitxers del superusuari. Finalment, utilitzar el +paràmetre d'arrencada #{persistence}#. + +Si un usuari necessita múltiples volums de persistència del mateix tipus per +a diferents ubicacions o proves, com #{private}# i #{work}#, el paràmetre +d'arrencada #{persistence-label}# utilitzat juntament amb el paràmetre +d'arrencada #{persistence}# permetrà tenir diversos dispositius amb la +mateixa, però única, persistència. Un exemple seria si un usuari vol +utilitzar una partició amb persistència amb l'etiqueta #{private}# per a +dades personals com els marcadors d'un navegador, utilitzaria els paràmetres +d'arrencada: #{persistence}# #{persistence-label=private}#. I per +emmagatzemar dades relacionades amb el treball, com a documents, projectes +de recerca o d'un altre tipus, utilitzaria els paràmetres d'arrencada: +#{persistence}# #{persistence-label=work}#. + +És important recordar que aquests volums, #{private}# i #{work}#, també +necessiten tenir un fitxer #{persistence.conf}# en la seva arrel. La pàgina +de manual de live-boot conté més informació sobre com utilitzar aquestes +etiquetes amb els noms més antics. + +3~ Persistència amb xifratge + +Utilitzar la persistència vol dir que algunes dades sensibles poden quedar +exposades a risc. Especialment si les dades persistents s'emmagatzemen en un +dispositiu portàtil com una memòria USB o un disc dur extern. És llavors +quan el xifrat entra en joc. Fins i tot si el procediment pot semblar +complicat a causa de la quantitat de passos que s'han de fer, és molt fàcil +manejar particions xifrades amb live-boot. Per a utilitzar *{luks}*, que és +el tipus de xifrat compatible, es necessita instal·lar /{cryptsetup}/ tant +en la màquina que crearà la partició xifrada com en el sistema en viu amb +que es va a utilitzar la partició persistent xifrada. + +Per a instal·lar /{cryptsetup}/ a la nostra màquina: + +code{ + + # apt-get install cryptsetup + +}code + +Per a instal·lar /{cryptsetup}/ en el sistema viu, afegir-lo a una +package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Una cop tinguem el nostre sistema en viu amb /{cryptsetup}/, bàsicament, +només hem de crear una nova partició, xifrar-la i arrencar amb els +paràmetres #{persistence}# i #{persistence-encryption=luks}#. Podríem haver +anticipat aquest pas i afegit els paràmetres d'arrencada seguint el +procediment habitual: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Anem a entrar en els detalls per a tothom que no està familiaritzat amb el +xifrat. En el següent exemple utilitzarem una partició en un dispositiu USB +que correspon a #{/dev/sdc2}#. Tenir en compte que cal determinar quina +partició és la que es va a utilitzar en cada cas específic. + +El primer pas és connectar la memòria usb i determinar de quin dispositiu es +tracta. La manera més recomanable per a llistar dispositius és utilitzar +#{ls -l /dev/disk/by-id}#. Després d'això, crear una nova partició i, a +continuació, xifrar-la amb una frase de contrasenya de la següent manera: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +A continuació, obrir la partició luks al mapeador de dispositius +virtuals. Es pot utilitzar qualsevol nom que es desitgi. Aquí utilitzem +*{live}* com a exemple: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +El següent pas és omplir el dispositiu amb zeros abans de crear el sistema +de fitxers: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Ara, estem preparats per a crear el sistema de fitxers. Noteu que estem +afegint l'etiqueta #{persistence}# perquè el dispositiu es munti com a +magatzem de persistència durant l'arrencada. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +Per continuar amb la nostra configuració, necessitem muntar el dispositiu, +per exemple, a #{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +I crear el fitxer #{persistence.conf}# a l'arrel de la partició. Això és, +com s'ha explicat abans, estrictament necessari. Veure {El fitxer +persistence.conf}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Desmuntar el punt de muntatge: + +code{ + + # umount /mnt + +}code + +I opcionalment, encara que podria ser una bona manera de protegir les dades +que acabem d'agregar a la partició, podem tancar el dispositiu: + +code{ + + # cryptsetup luksClose live + +}code + +Anem a resumir el procés. Fins ara, hem creat un sistema viu capaç de +manejar xifratge, que es pot copiar a una memòria USB com s'explica a +{Copiar una imatge ISO híbrida en un dispositiu +USB}#copying-iso-hybrid-to-usb. També hem creat una partició xifrada, que es +pot situar en la mateixa memòria USB per portar a tot arreu i hem configurat +la partició xifrada per ser utilitzada com a magatzem de persistència. Així +que ara, només hem de arrencar el sistema en viu. En el moment d'arrencar, +live-boot ens preguntarà la frase de contrasenya i muntarà la partició +xifrada per a ser utilitzada per a la persistència. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_installation.ssi new file mode 100644 index 0000000..95dac67 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_installation.ssi @@ -0,0 +1,182 @@ +:B~ Instal·lació + +1~installation Instal·lació + +2~requirements Requisits + +La construcció d'imatges en viu té molts pocs requisits. + +_* Accés de superusuari (root) + +_* Una versió actualitzada de live-build + +_* Una shell compatible amb POSIX, com ara /{bash}/ o /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6.x o superior. + +Tenir en compte que no cal usar Debian o una distribució derivada de Debian +ja que live-build funcionarà en gairebé qualsevol distribució amb els +requisits anteriors. + +2~installing-live-build Instal·lació de live-build + +Es pot instal·lar live-build en un nombre de maneres diferentes: + +_* Des del repositori Debian + +_* A partir del codi font + +_* A partir d'instantànies + +Si s'utilitza Debian, la manera recomanada és instal·lar live-build des del +repositori de Debian. + +3~ Des del repositori de Debian + +Només cal instal·lar live-build com qualsevol altre paquet: + +code{ + + # apt-get install live-build + +}code + +3~ A partir del codi font + +live-build es desenvolupa utilitzant el sistema de control de versions Git. +En els sistemes basats en Debian, això és proporcionat pel paquet git. Per a +comprovar l'últim codi, executar: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +Es pot construir i instal·lar un paquet Debian pròpi mitjançant l'execució +de: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Ara instal·lar qualsevol dels fitxers #{.deb}# recent construïts que ens +interessen, per exemple, + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +Es pot instal·lar live-build directament al sistema mitjançant l'execució +de: + +code{ + + # make install + +}code + +i desinstal·lar amb: + +code{ + + # make uninstall + +}code + +3~ A partir d'instantànies + +Si no es desitja construir o instal·lar live-build a partir de les fonts, es +pot utilitzar les instantànies. Aquestes es construeixen automàticament a +partir de l'última versió del Git, i estan disponibles a +http://live-systems.org/debian/. + +2~ Instal.lació de live-boot i live-config + +*{Nota:}* No cal instal·lar live-boot o live-config en el sistema per a crear sistemes personalitzats en viu. No obstant, això no farà cap mal i és útil per a fins de referència. Si només es vol la documentació, ara es poden instal·lar els paquets /{live-boot-doc}/ i /{live-config-doc}/ per separat. + +3~ Des del repositori de Debian + +Tots dos, live-boot i live-config, estan disponibles al arxiu de Debian, +d'una manera similar a {Instal·lació de live-build}#installing-live-build. + +3~ A partir del codi font + +Per a utilitzar les darreres fonts del git, es pot seguir el procés +seguent. Assegurar-se d'estar familiaritzat amb els termes esmentats a +{Termes}#terms. + +_* Clonar les fonts de live-boot i live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consultar les pàgines del manual de live-boot i live-config per a més +detalls sobre la seva personalització si aquesta és la raó per a construir +aquests paquets a partir de les fonts. + +_* Crear els fitxers .deb de live-boot i live-config + +S'ha de crear ja sigui en la distribució de destinació o en un chroot que +contingui la plataforma de destinació: és a dir, si el objectiu és +${testing} llavors s'ha de construir contra ${testing}. + +Es pot utilitzar un constructor personal, com ara /{pbuilder}/ o /{sbuild}/ +si es necessita crear live-boot per a una distribució de destinació +diferenta del sistema de construcció. Per exemple, per a les imatges en viu +de ${testing}, crear live-boot en un chroot ${testing}. Si la distribució de +destinació per casualitat coincideix amb la distribució del sistema de +construcció, es pot construir directament en el sistema de construcció amb +#{dpkg-buildpackage}# (proporcionat pel paquet /{dpkg-dev}/): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Utilitzar tots el fitxers .deb generats que calguin + +Com live-boot i live-config són instal·lats per el sistema de construcció +live-build, instal·lar els paquets en el sistema amfitrió no és suficient: +s'ha de tractar els .deb generats com si fossin uns paquets +personalitzats. Ja que el propòsit per a construir aquests paquets a partir +del codi font és per a provar coses noves a curt termini abans del +llançament oficial, seguir els pasos de {Instal·lació de paquets modificats +o de tercers}#installing-modified-or-third-party-packages per a incloure +temporalment els paquets rellevants en la configuració. En particular, cal +observar que ambdós paquets es divideixen en una part genèrica, una part de +documentació i un o més back-ends. Incloure la part genèrica, només un dels +back-ends que coincideixi amb la configuració, i, opcionalment, la +documentació. Suposant que s'està construint una imatge en viu en el +directori actual i que s'han generat tots els .deb per a una única versió +dels dos paquets al directori superior, aquestes ordres de bash són per a +copiar tots els paquets importants, incloent-hi els back-ends per defecte: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ A partir d'instantànies + +Es pot deixar que live-build utilitzi les darreres instantànies de live-boot +i live-config configurant el repositori de tercers live-systems.org en el +directori de configuració de live-build. diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_managing_a_configuration.ssi new file mode 100644 index 0000000..72c71ac --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_managing_a_configuration.ssi @@ -0,0 +1,140 @@ +:B~ Gestió d'una configuració + +1~managing-a-configuration Gestió d'una configuració + +En aquest capítol s'explica com gestionar una configuració d'un sistema en +viu des de la seva creació inicial, a través de revisions i versions +successives de tant el programari live-build com de la imatge en viu en si +mateixa. + +2~ Gestionar canvis en la configuració + +Les configuracions de sistemes en viu poques vegades són perfectes al primer +intent. Passar opcions a #{lb config}# des de la línea d'ordres pot estar be +per a construir una imatge una vegada, però és més típic revisar aquestes +opcions i construir de nou fins que se'n estigui satisfet. Per a donar +suport a aquests canvis, es poden utilitzar scripts auto que assegurin que +la configuració es manté en un estat consistent. + +3~ Per què utilitzar scripts auto? Què fan? + +L'ordre #{lb config}# emmagatzema les opcions que se li passen als fitxers +de #{config/*}#, juntament amb moltes altres opcions que estan establertes +als valors per defecte. Si s'executa un cop més, #{lb config}# no es +restablirà cap de les opcios dependents basades en les opcions +inicials. Així, per exemple, si s'executa de nou #{lb config}# amb un nou +valor per a #{--binary-images}#, totes les opcions que en depenen que es van +omplir per al tipus de imatge per defecte ja no poden funcionar amb la +nova. Aquests fitxers no estan destinats a ser llegits o +editats. S'emmagatzemen els valors de més de cent opcions, i ningú pot veure +les opcions que s'han especificat realment. I finalment, si s'executa #{lb +config}# i a continuació s'actualitza live-build i el nom d'una opció +canvia, #{config/*}# encara contindrà les variables de l'opció vella que ja +no són vàlides. + + Per totes aquestes raons, els scripts #{auto/*}# ens fan la vida més +fàcil. Són simples embolcalls per les ordres #{lb config}#, #{lb build}# i +#{lb clean}# dissenyats per ajudar a gestionar una configuració. Només cal +crear un script #{auto/config}# que contingui totes les opcions que es +desitgin per a #{lb config}#, i un #{auto/clean}# que elimini els fitxers +que continguin diversos valors de variables de configuració, i el script +#{auto/build}# guarda un #{build.log}# de cada construcció. Cada vegada que +s'executi l'ordre #{lb}# corresponent, aquests fitxers seran executats +automàticament. L'ús d'aquests scripts assegurarà que la configuració sigui +més senzilla de llegir i que guardi una coherència interna d'una reversió a +una altra. A més a més serà més fàcil identificar i solucionar les opcions +que s'han de canviar al actualitzar d'una versió de live-build a la següent +després de llegir la documentació. + +3~ Utilitzar scripts auto d'exemple + +Per a més comoditat, live-build ve amb uns scripts d'exemple per a copiar i +editar. Iniciar una nova configuració per defecte, i a continuació, copiar +els exemples: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Editar #{auto/config}#, afegint les opcions més adients. Per exemple: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Ara, cada vegada que s'utilitzi #{lb config}#, #{auto/config}# restablirà la +configuració basada en aquestes opcions. Quan es vulgui fer canvis, editar +les opcions d'aquest fitxer en lloc de passar-les a #{lb config}#. Quan +s'utilitza #{lb clean}#, #{auto/clean}# netejarà els fitxers de #{config/*}# +juntament amb els altres productes de construcció. I, finalment, quan +s'utilitza #{lb build}#, es crea un log de la construcció mitjançant +#{auto/build}# anomenat #{build.log}#. + +*{Nota:}* Aquí s'utilitza un paràmetre especial #{noauto}# per a suprimir un altra crida a #{auto/config}#, la qual cosa impedeix la recursivitat infinita. Assegurar-se de no eliminarlo accidentalment fent canvis. També, tenir cura de que quan es divideix l'ordre #{lb config}# a través de diverses línies per a facilitar la lectura, com es mostra en l'exemple anterior, no s'oblidi la barra invertida (\) al final de cada línia que segueix a la següent. + +2~clone-configuration-via-git Clonar una configuració publicada via Git + +Utilitzar l'opció #{lb config --config}# per a clonar un repositori Git que +contingui una configuració en viu. Si es vol basar la configuració en un +repositori mantingut pel ${project}, mirar el repositori a +http://live-systems.org/gitweb/ amb el nom #{live-images}# sota el títol +#{Packages}#. Aquest repositori conté les configuracions per a les {imatges +prefabricades}#downloading-prebuilt-images + +Per exemple, per a construir una imatge standard, utilitzar el repositori +#{live-images}# de la manera següent: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Editar #{auto/config}# i qualsevol altra cosa necessària dins l'arbre +#{config}# per a satisfer les necessitats pròpies. Per exemple, per a fer +les imatges prefabricades no oficials que contenen paquets de la secció +non-free simplement s'afegeix #{--archive-areas "main contrib non-free"}#. + +Si es desitja, es pot definir una drecera en la configuració de Git, afegint +el següent a #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +Això permet utilitzar #{lso:}# en qualsevol lloc on cal especificar la +direcció d'un repositori git. També es pot omitir el sufix #{.git}#, i així, +començar una nova imatge amb aquesta configuració és tan fàcil com: + +code{ + + $ lb config --config lso:live-images + +}code + +Clonar tot el repositori #{live-images}# còpia les configuracions +utilitzades per diverses imatges. Si es vol construir una imatge diferent +després d'haver acabat amb la primera, canviar a un altre directori i un +altre cop i, opcionalment, fer els canvis per a adaptar-les a les +necessitats pròpies. + +En qualsevol cas, recordar que cada vegada que s'ha de construir una imatge, +s'ha de fer com a superusuari: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/ca/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ca/user_overview.ssi new file mode 100644 index 0000000..8258ca0 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ca/user_overview.ssi @@ -0,0 +1,138 @@ +:B~ Descripció general de les eines + +1~overview-of-tools Descripció general de les eines + +Aquest capítol conté un resum de les tres eines principals utilitzades en la +construcció dels sistemes en viu: live-build, live-boot i live-config. + +2~live-build El paquet live-build + +live-build és un conjunt de scripts per a crear sistemes en viu. Aquests +scripts també s'anomenen «ordres». + +La idea darrere de live-build és ser un marc que utilitza un directori de +configuració per automatitzar completament i personalitzar tots els aspectes +de la construcció d'una imatge en viu. + +Molts conceptes són similars als utilitzats per a crear paquets Debian amb +/{debhelper}/: + +_* Els scripts tenen una ubicació central per a la configuració del seu +funcionament. Amb /{debhelper}/ aquest és el subdirectori #{debian/}# d'un +arbre de paquets. Per exemple, dh_install buscarà, entre altres, un fitxer +anomenat #{debian/install}# per a determinar quins fitxers han d'existir en +un paquet binari en particular. De la mateixa manera, live-build emmagatzema +la seva configuració per complet sota un subdirectori #{config/}#. + +_* Els scripts són independents - és a dir, sempre és segur executar cada +ordre. + +A diferència de /{debhelper}/, live-build proporciona les eines per a +generar un directori de configuració en esquelet. Això podria ser considerat +similar a eines com ara /{dh-make}/. Per a més informació sobre aquestes +eines, seguiu llegint, ja que la resta d'aquesta secció discuteix les quatre +ordres més importants. Tenir en compte que van precedices de #{lb}# que és +una funció genèrica per a les ordres de live-build. + +_* *{lb config}*: Responsable d'inicialitzar un directori de configuració +per al sistema en viu. Consultar {L'ordre lb config}#lb-config per a més +informació. + +_* *{lb build}*: Responsable d'iniciar la creació d'un sistema en +viu. Consultar {L'ordre lb build}#lb-build per a més informació. + +_* *{lb clean}*: Responsable d'eliminar parts de la construcció d'un sistema +viu. Consultar {L'ordre lb clean}#lb-clean per a més informació. + +3~lb-config L'ordre #{lb config}# + +Com s'ha dit a {live-build}#live-build, les seqüències d'ordres que formen +part de live-build llegeixen la seva configuració amb l'ordre #{source}# +d'un únic directori anomenat #{config/}#. Com la construcció d'aquest +directori a mà, seria molt costós i propens a errors, es pot utilitzar +l'ordre #{lb config}# per a crear l'arbre inicial de configuració en +esquelet. + +Executar #{lb config}# sense arguments crea el subdirectori #{config/}# que +s'omple amb alguns paràmetres per defecte en fitxers de configuració, i dos +arbres de subdirectoris en esquelet que s'anomenen #{auto/}# i #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Utilitzar #{lb config}# sense cap tipus d'arguments seria convenient per als +usuaris que necessiten una imatge molt bàsica, o que tinguin la intenció de +proporcionar una configuració més completa més tard mitjançant +#{auto/config}# (Veure {Gestió d'una configuració}#managing-a-configuration +per a més detalls). + +Normalment, s'haurà d'especificar algunes opcions. Per exemple, per a +especificar quin gestor de paquets utilitzar durant la construcció de la +imatge: + +code{ + + $ lb config --apt aptitude + +}code + +És possible especificar diverses opcions, com ara: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +Una llista completa d'opcions està disponible a la pàgina del manual +#{lb_config}#. + +3~lb-build L'ordre #{lb build}# + +L'ordre #{lb build}# llegeix la configuració del directori #{config/}#. A +continuació, executa les ordres de nivell inferior necessàries per a +construir el sistema en viu. + +3~lb-clean L'ordre #{lb clean}# + +L'ordre #{lb clean}# s'encarrega d'eliminar diverses parts d'una construcció +per a que altres construccions posteriors puguin començar des d'un estat +net. Per defecte, es netegen les etapes #{chroot}#, #{binary}# i #{source}#, +però la caché es manté intacta. A més, es poden netejar etapes +individuals. Per exemple, si s'han fet canvis que només afecten a la fase +binary, utilitzar #{lb clean --binary}# abans de construir un nou binary. Si +els canvis modifiquen el bootstrap i/o la caché de paquets, per exemple, +canvis en les opcions #{--mode}#, #{--architecture}# o #{--bootstrap}#, s'ha +d'utilitzar #{lb clean --purge}#. Veure la pàgina del manual de +#{lb_clean}# per a una llista completa d'opcions. + +2~live-boot El paquet live-boot + +live-boot és un conjunt de scripts per a proporcionar hooks a +/{initramfs-tools}/, que s'utilitzen per a generar un initramfs capaç +d'arrencar sistemes vius, com ara els creats per live-build. Això inclou les +ISOs dels sistemes en viu, netboot tarballs i imatges per a memòries USB. + +En el moment d'arrencar, buscarà medis de només lectura que continguin un +directori #{/live/}# on s'emmagatzema un sistema de fitxers arrel (sovint +una imatge de un sistema de fitxers comprimit squashfs). Si el troba, crearà +un entorn d'escriptura, utilitzant aufs, per a que puguin arrencar sistemes +com Debian o similars. + +Més informació sobre ramfs inicial a Debian es pot trobar al Debian Linux +Kernel Handbook http://kernel-handbook.alioth.debian.org/ al capítol sobre +initramfs. + +2~live-config El paquet live-config + +live-config consta dels scripts que s'executen durant l'arrencada després de +live-boot per a configurar el sistema en viu de forma automàtica. S'ocupa de +tasques com ara l'establiment de les locales, el nom d'amfitrió, la zona +horària, crear l'usuari en viu, l'inhibició de tasques de cron i l'inici +automàtic de sessió per a l'usuari en viu. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/de/about_manual.ssi new file mode 100644 index 0000000..6ff976b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/about_manual.ssi @@ -0,0 +1,270 @@ +:B~ Über dieses Handbuch + +1~about-manual Über dieses Handbuch + +This manual serves as a single access point to all documentation related to +the ${project} and in particular applies to the software produced by the +project for the Debian 9.0 "${stable}" release. An up-to-date version can +always be found at http://live-systems.org/ + +While live-manual is primarily focused on helping you build a live system +and not on end-user topics, an end user may find some useful information in +these sections: {The Basics}#the-basics covers downloading prebuilt images +and preparing images to be booted from media or the network, either using +the web builder or running live-build directly on your system. {Customizing +run time behaviours}#customizing-run-time-behaviours describes some options +that may be specified at the boot prompt, such as selecting a keyboard +layout and locale, and using persistence. + +Einige der erwähnten Befehle im Text müssen als Superuser ausgeführt +werden. Dies kann entweder dadurch erreicht werden, indem zuerst auf den +root Benutzer gewechselt wird mittels #{su}# oder durch die Benutzung von +#{sudo}#. Um die Befehle welche als unprivilegierter Benutzer ausgeführt +werden können und diesen welche Superuser Rechte benötigen, sind den +Befehlen #{$}# respektive #{#}# vorangestellt. Dieses Symbol ist nicht Teil +des Befehls. + +2~ Für die Ungeduldigen + +Obowhl wir denken dass alles in diesem Handbuch mehr oder weniger für die +einen oder anderen Benutzer wichtig ist, sind wir uns bewusst, dass es sich +um viel Material handelt. Für ein schnelles Erfolgserlebnis in der Anwendung +dieser Software schlagen wir die folgende Reihenfolge vor, bevor sie sich +mit den Details befassen: + +First, read this chapter, {About this manual}#about-manual, from the +beginning and ending with the {Terms}#terms section. Next, skip to the three +tutorials at the front of the {Examples}#examples section designed to teach +you image building and customization basics. Read {Using the +examples}#using-the-examples first, followed by {Tutorial 1: A default +image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and +finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these +tutorials, you will have a taste of what can be done with live systems. + +We encourage you to return to more in-depth study of the manual, perhaps +next reading {The basics}#the-basics, skimming or skipping {Building a +netboot image}#building-netboot-image, and finishing by reading the +{Customization overview}#customization-overview and the chapters that follow +it. By this point, we hope you are thoroughly excited by what can be done +with live systems and motivated to read the rest of the manual, +cover-to-cover. + +2~terms Begriffe + +_* *{Live system}*: An operating system that can boot without installation +to a hard drive. Live systems do not alter local operating system(s) or +file(s) already installed on the computer hard drive unless instructed to do +so. Live systems are typically booted from media such as CDs, DVDs or USB +sticks. Some may also boot over the network (via netboot images, see +{Building a netboot image}#building-netboot-image), and over the Internet +(via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). + +_* *{Live medium}*: As distinct from live system, the live medium refers to +the CD, DVD or USB stick where the binary produced by live-build and used to +boot the live system is written. More broadly, the term also refers to any +place where this binary resides for the purposes of booting the live system, +such as the location for the network boot files. + +_* *{${project}}*: The project which maintains, among others, the live-boot, +live-build, live-config, live-tools and live-manual packages. + +_* *{Host system}*: The environment used to create the live system. + +_* *{Target system}*: The environment used to run the live system. + +_* *{live-boot}*: A collection of scripts used to boot live systems. + +_* *{live-build}*: A collection of scripts used to build customized live +systems. + +_* *{live-config}*: A collection of scripts used to configure a live system +during the boot process. + +_* *{live-tools}*: A collection of additional scripts used to perform useful +tasks within a running live system. + +_* *{live-manual}*: This document is maintained in a package called +live-manual. + +_* *{Debian Installer (d-i)}*: The official installation system for the +Debian distribution. + +_* *{Boot parameters}*: Parameters that can be entered at the bootloader +prompt to influence the kernel or live-config. + +_* *{chroot}*: The /{chroot}/ program, #{chroot(8)}#, enables us to run +different instances of the GNU/Linux environment on a single system +simultaneously without rebooting. + +_* *{Binary image}*: A file containing the live system, such as +live-image-i386.hybrid.iso or live-image-i386.img. + +_* *{Target distribution}*: The distribution upon which your live system +will be based. This can differ from the distribution of your host system. + +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently +codenamed ${stable}, contains the latest officially released distribution of +Debian. The *{testing}* distribution, temporarily codenamed ${testing}, is +the staging area for the next *{stable}* release. A major advantage of using +this distribution is that it has more recent versions of software relative +to the *{stable}* release. The *{unstable}* distribution, permanently +codenamed sid, is where active development of Debian occurs. Generally, this +distribution is run by developers and those who like to live on the +edge. Throughout the manual, we tend to use codenames for the releases, such +as ${testing} or sid, as that is what is supported by the tools themselves. + +2~ Autoren + +Liste der Autoren (in alphabetischer Reihenfolge): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contributing to this document + +This manual is intended as a community project and all proposals for +improvements and contributions are extremely welcome. Please see the section +{Contributing to the project}#contributing-to-project for detailed +information on how to fetch the commit key and make good commits. + +3~applying-changes Applying changes + +In order to make changes to the English manual you have to edit the right +files in #{manual/en/}# but prior to the submission of your contribution, +please preview your work. To preview the live-manual, ensure the packages +needed for building it are installed by executing: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +You may build the live-manual from the top level directory of your Git +checkout by executing: + +code{ + + $ make build + +}code + +Since it takes a while to build the manual in all supported languages, +authors may find it convenient to use one of the fast proofing shortcuts +when reviewing the new documentation they have added to the English +manual. Using #{PROOF=1}# builds live-manual in html format, but without the +segmented html files, and using #{PROOF=2}# builds live-manual in pdf +format, but only the A4 and letter portraits. That is why using either of +the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: + +code{ + + $ make build PROOF=1 + +}code + +When proofing one of the translations it is possible to build only one +language by executing, e.g: + +code{ + + $ make build LANGUAGES=de + +}code + +It is also possible to build by document type, e.g: + +code{ + + $ make build FORMATS=pdf + +}code + +Or combine both, e.g: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +After revising your work and making sure that everything is fine, do not use +#{make commit}# unless you are updating translations in the commit, and in +that case, do not mix changes to the English manual and translations in the +same commit, but use separate commits for each. See the +{Translation}#translation section for more details. + +3~translation Translation + +In order to translate live-manual, follow these steps depending on whether +you are starting a translation from scratch or continue working on an +already existing one: + +_* Start a new translation from scratch + +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and +*{index.html.in.pot}* files in #{manual/pot/}# to your language with your +favourite editor (such as /{poedit}/) and send the translated #{.po}# files +to the mailing list to check their integrity. live-manual's integrity check +not only ensures that the #{.po}# files are 100% translated but it also +detects possible errors. + +_2* Once checked, to enable a new language in the autobuild it is enough to +add the initial translated files to #{manual/po/${LANGUAGE}/}# and run +#{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the +name of the language and its name in English between brackets. + +_* Continue with an already started translation + +_2* If your target language has already been added, you can randomly +continue translating the remaining .po files in #{manual/po/${LANGUAGE}/}# +using your favourite editor (such as /{poedit}/). + +_2* Do not forget that you need to run #{make commit}# to ensure that the +translated manuals are updated from the .po files and then you can review +your changes launching #{make build}# before #{git add .}#, #{git commit -m +"Translating..."}# and #{git push}#. Remember that since #{make build}# can +take a considerable amount of time, you can proofread languages individually +as explained in {Applying changes}#applying-changes + +After running #{make commit}# you will see some text scroll by. These are +basically informative messages about the processing status and also some +hints about what can be done in order to improve live-manual. Unless you see +a fatal error, you usually can proceed and submit your contribution. + +live-manual comes with two utilities that can greatly help translators to +find untranslated and changed strings. The first one is "make translate". It +launches an script that tells you in detail how many untranslated strings +there are in each .po file. The second one, the "make fixfuzzy" target, only +acts upon changed strings but it helps you to find and fix them one by one. + +Keep in mind that even though these utilities might be really helpful to do +translation work on the command line, the use of an specialized tool like +/{poedit}/ is the recommended way to do the task. It is also a good idea to +read the Debian localization (l10n) documentation and, specifically to +live-manual, the {Guidelines for translators}#guidelines-translators. + +*{Note:}* You can use #{make clean}# to clean your git tree before pushing. This step is not compulsory thanks to the .gitignore file but it is a good practice to avoid committing files involuntarily. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/de/about_project.ssi new file mode 100644 index 0000000..667c4ad --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/about_project.ssi @@ -0,0 +1,102 @@ +:B~ About the ${project} + +1~about-project About the ${project} + +2~ Motivation + +3~ What is wrong with current live systems + +When ${project} was initiated, there were already several Debian based live +systems available and they are doing a great job. From the Debian +perspective most of them have one or more of the following disadvantages: + +_* They are not Debian projects and therefore lack support from within +Debian. + +_* They mix different distributions, e.g. *{testing}* and *{unstable}*. + +_* They support i386 only. + +_* They modify the behaviour and/or appearance of packages by stripping them +down to save space. + +_* They include packages from outside of the Debian archive. + +_* They ship custom kernels with additional patches that are not part of +Debian. + +_* They are large and slow due to their sheer size and thus not suitable for +rescue issues. + +_* They are not available in different flavours, e.g. CDs, DVDs, USB-stick +and netboot images. + +3~ Why create our own live system? + +Debian is the Universal Operating System: Debian has a live system to show +around and to accurately represent the Debian system with the following main +advantages: + +_* It is a subproject of Debian. + +_* It reflects the (current) state of one distribution. + +_* It runs on as many architectures as possible. + +_* It consists of unchanged Debian packages only. + +_* It does not contain any packages that are not in the Debian archive. + +_* It uses an unaltered Debian kernel with no additional patches. + +2~ Philosophy + +3~ Only unchanged packages from Debian "main" + +We will only use packages from the Debian repository in the "main" +section. The non-free section is not part of Debian and therefore cannot be +used for official live system images. + +We will not change any packages. Whenever we need to change something, we +will do that in coordination with its package maintainer in Debian. + +As an exception, our own packages such as live-boot, live-build or +live-config may temporarily be used from our own repository for development +reasons (e.g. to create development snapshots). They will be uploaded to +Debian on a regular basis. + +3~ No package configuration of the live system + +In this phase we will not ship or install sample or alternative +configurations. All packages are used in their default configuration as they +are after a regular installation of Debian. + +Whenever we need a different default configuration, we will do that in +coordination with its package maintainer in Debian. + +A system for configuring packages is provided using debconf allowing custom +configured packages to be installed in your custom produced live system +images, but for the {prebuilt live images}#downloading-prebuilt-images we +choose to leave packages in their default configuration, unless absolutely +necessary in order to work in the live environment. Wherever possible, we +prefer to adapt packages within the Debian archive to work better in a live +system versus making changes to the live toolchain or {prebuilt image +configurations}#clone-configuration-via-git. For more information, please +see {Customization overview}#customization-overview. + +2~contact Contact + +_* *{Mailing list}*: The primary contact for the project is the mailing list +at https://lists.debian.org/debian-live/. You can email the list directly by +addressing your mail to debian-live@lists.debian.org. The list archives are +available at https://lists.debian.org/debian-live/. + +_* *{IRC}*: A number of users and developers are present in the #debian-live +channel on irc.debian.org (OFTC). When asking a question on IRC, please be +patient for an answer. If no answer is forthcoming, please email the mailing +list. + +_* *{BTS}*: The {Debian Bug Tracking System}https://www.debian.org/Bugs/ +(BTS) contains details of bugs reported by users and developers. Each bug is +given a number, and is kept on file until it is marked as having been dealt +with. For more information, please see {Reporting bugs}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/de/appendix_style-guide.ssi new file mode 100644 index 0000000..1bba13e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/appendix_style-guide.ssi @@ -0,0 +1,364 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account +when writing technical documentation for live-manual. They are divided into +linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers +of English. So as a general rule try to use short, meaningful sentences, +followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a +suggestion to try to avoid, as much as possible, complex subordinate +sentences that make the text difficult to understand for non-native speakers +of English. + +_* /{Variety of English}/ + +The most widely spread varieties of English are British and American so it +is very likely that most authors will use either one or the other. In a +collaborative environment, the ideal variety would be "International +English" but it is very difficult, not to say impossible, to decide on which +variety among all the existing ones, is the best to use. + +We expect that different varieties may mix without creating +misunderstandings but in general terms you should try to be coherent and +before deciding on using British, American or any other English flavour at +your discretion, please take a look at how other people write and try to +imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely +unrelated to live-manual. Technical writing should be as neutral as +possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make +references to the third person singular preferably use "they" rather than +"he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +Go straight to the point and do not wander around aimlessly. Give as much +information as necessary but do not give more information than necessary, +this is to say, do not explain unnecessary details. Your readers are +intelligent. Presume some previous knowledge on their part. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several +other languages. This implies that a number of people will have to do an +extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +As suggested before, it is almost impossible to standardize a collaborative +document into a perfectly unified whole. However, every effort on your side +to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Be descriptive}/ + +It is preferable to describe the point in one or several paragraphs than +merely using a number of sentences in a typical "changelog" style. Describe +it! Your readers will appreciate it. + +_* /{Dictionary}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not +know how to express certain concepts in English. But keep in mind that a +dictionary can either be your best friend or can turn into your worst enemy +if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million +words). Many of these words are borrowings from other languages. When +looking up the meaning of words in a bilingual dictionary the tendency of a +non-native speaker of English is to choose the one that sounds more similar +in their mother tongue. This often turns into an excessively formal +discourse which does not sound quite natural in English. + +As a general rule, if a concept can be expressed using different synonyms, +it is a good advice to choose the first word proposed by the dictionary. If +in doubt, choosing words of Germanic origin (Usually monosyllabic words) is +often the right thing to do. Be warned that these two techniques might +produce a rather informal discourse but at least your choice of words will +be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely +helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search +engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign +language you cannot help falling from time to time in the trap of the so +called "false friends", words that look similar in two languages but whose +meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may +convey a completely different meaning from what their individual words seem +to mean. Sometimes, idioms might be difficult to understand even for native +speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical +writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand +and above all contractions that try to imitate the spoken language. Not to +mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +It is important that authors test their examples before adding them to +live-manual to ensure that everything works as described. Testing on a clean +chroot or VM can be a good starting point. Besides, it would be ideal if the +tests were then carried out on different machines with different hardware to +spot possible problems that may arise. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, +after all, just an example. + +It is often better to use a line that only applies to a specific case than +using abstractions that may confuse your readers. In this case you can +provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some +potentially dangerous commands that, if misused, may cause data loss or +other similar undesirable effects. In this case you should provide a +thorough explanation of the possible side effects. + +_* /{External links}/ + +Links to external sites should only be used when the information on those +sites is crucial when it comes to understanding a special point. Even so, +try to use links to external sites as sparsely as possible. Internet links +are likely to change from time to time resulting in broken links and leaving +your arguments in an incomplete state. + +Besides, people who read the manual offline will not have the chance to +follow those links. + +_* /{Avoid branding and things that violate the license under which the +manual is published}/ + +Try to avoid branding as much as possible. Keep in mind that other +downstream projects might make use of the documentation you write. So you +are complicating things for them if you add certain specific material. + +live-manual is licensed under the GNU GPL. This has a number of implications +that apply to the distribution of the material (of any kind, including +copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence + of events. + + - Once you have somehow organized those ideas in your mind write a first + draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names + of the releases, such as ${testing} or sid, should not be capitalized + when referred to as code names. In order to check the spelling you can + run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, +1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup +below. + +If you have to enumerate a series of steps or stages in your description, +you can also use ordinal numbers: First, second, third ... or First, Then, +After that, Finally ... Alternatively you can use bulleted items. + +_* /{Markup}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to +process the text files and produce a multiple format output. It is +recommended to take a look at {SiSU's +manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get +familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to +highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to +remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account +when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the +translation rules that apply to their specific languages. Usually, +translation groups and mailing lists provide information on how to produce +translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +The role of the translator is to convey as faithfully as possible the +meaning of words, sentences, paragraphs and texts as written by the original +authors into their target language. + +So they should refrain from adding personal comments or extra bits of +information of their own. If they want to add a comment for other +translators working on the same documents, they can leave it in the space +reserved for that. That is, the header of the strings in the *{po}* files +preceded by a number sign *{#}*. Most graphical translation programs can +automatically handle those types of comments. + +_* /{TN, Translator's Note}/ + +It is perfectly acceptable however, to include a word or an expression in +brackets in the translated text if, and only if, that makes the meaning of a +difficult word or expression clearer to the reader. Inside the brackets the +translator should make evident that the addition was theirs using the +abbreviation "TN" or "Translator's Note". + +_* /{Impersonal sentences}/ + +Documents written in English make an extensive use of the impersonal form +"you". In some other languages that do not share this characteristic, this +might give the false impression that the original texts are directly +addressing the reader when they are actually not doing so. Translators must +be aware of that fact and reflect it in their language as accurately as +possible. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to +translators. Double check the meaning of suspicious false friends if in +doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* +files will find many markup features in the strings. They can translate the +text anyway, as long as it is translatable, but it is extremely important +that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in +the translation is the only way to score a 100% complete translation. And +even though it means more work at first because it might require the +intervention of the translators if the code changes, it is the best way, in +the long run, to identify what has already been translated and what has not +when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original +texts. Be careful to press the "Enter" key or type *{\n}* if they appear in +the original files. These newlines often appear, for instance, in the code +blocks. + +Make no mistake, this does not mean that the translated text needs to have +the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths diff --git a/markup/pod-samples/pod/live-manual/media/text/de/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/de/examples.ssi new file mode 100644 index 0000000..e3cc4c6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/examples.ssi @@ -0,0 +1,434 @@ +:B~ Beispiele + +1~examples Examples + +This chapter covers example builds for specific use cases with live +systems. If you are new to building your own live system images, we +recommend you first look at the three tutorials in sequence, as each one +teaches new techniques that will help you use and understand the remaining +examples. + +2~using-the-examples Using the examples + +To use these examples you need a system to build them on that meets the +requirements listed in {Requirements}#requirements and has live-build +installed as described in {Installing live-build}#installing-live-build. + +Note that, for the sake of brevity, in these examples we do not specify a +local mirror to use for the build. You can speed up downloads considerably +if you use a local mirror. You may specify the options when you use #{lb +config}#, as described in {Distribution mirrors used at build +time}#distribution-mirrors-build-time, or for more convenience, set the +default for your build system in #{/etc/live/build.conf}#. Simply create +this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your +preferred mirror. All other mirrors used in the build will be defaulted from +these values. For example: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 Tutorial 1: A default image + +*{Use case:}* Create a simple first image, learning the basics of live-build. + +In this tutorial, we will build a default ISO hybrid live system image +containing only base packages (no Xorg) and some live system support +packages, as a first exercise in using live-build. + +You can't get much simpler than this: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examine the contents of the #{config/}# directory if you wish. You will see +stored here a skeletal configuration, ready to customize or, in this case, +use immediately to build a default image. + +Now, as superuser, build the image, saving a log as you build with #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Assuming all goes well, after a while, the current directory will contain +#{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly +in a virtual machine as described in {Testing an ISO image with +Qemu}#testing-iso-with-qemu and {Testing an ISO image with +VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media +or a USB flash device as described in {Burning an ISO image to a physical +medium}#burning-iso-image and {Copying an ISO hybrid image to a USB +stick}#copying-iso-hybrid-to-usb, respectively. + +2~tutorial-2 Tutorial 2: A web browser utility + +*{Use case:}* Create a web browser utility image, learning how to apply customizations. + +In this tutorial, we will create an image suitable for use as a web browser +utility, serving as an introduction to customizing live system images. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Our choice of LXDE for this example reflects our desire to provide a minimal +desktop environment, since the focus of the image is the single use we have +in mind, the web browser. We could go even further and provide a default +configuration for the web browser in +#{config/includes.chroot/etc/iceweasel/profile/}#, or additional support +packages for viewing various kinds of web content, but we leave this as an +exercise for the reader. + +Build the image, again as superuser, keeping a log as in {Tutorial +1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: A personalized image + +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. + +Since we will be changing our personalized image over a number of revisions, +and we want to track those changes, trying things experimentally and +possibly reverting them if things don't work out, we will keep our +configuration in the popular #{git}# version control system. We will also +use the best practice of autoconfiguration via #{auto}# scripts as described +in {Managing a configuration}#managing-a-configuration. + +3~ First revision + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Edit #{auto/config}# to read as follows: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Perform #{lb config}# to generate the config tree, using the #{auto/config}# +script you just created: + +code{ + + $ lb config + +}code + +Now populate your local package list: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +First, #{--architectures i386}# ensures that on our #{amd64}# build system, +we build a 32-bit version suitable for use on most machines. Second, we use +#{--linux-flavours 686-pae}# because we don't anticipate using this image on +much older systems. Third, we have chosen the /{lxde}/ task metapackage to +give us a minimal desktop. And finally, we have added two initial favourite +packages: /{iceweasel}/ and /{xchat}/. + +Now, build the image: + +code{ + + # lb build + +}code + +Note that unlike in the first two tutorials, we no longer have to type +#{2>&1 | tee build.log}# as that is now included in #{auto/build}#. + +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are +satisfied it works, it's time to initialize our #{git}# repository, adding +only the auto scripts we just created, and then make the first commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Second revision + +In this revision, we're going to clean up from the first build, add the +/{vlc}/ package to our configuration, rebuild, test and commit. + +The #{lb clean}# command will clean up all generated files from the previous +build except for the cache, which saves having to re-download packages. This +ensures that the subsequent #{lb build}# will re-run all stages to +regenerate the files from our new configuration. + +code{ + + # lb clean + +}code + +Now append the /{vlc}/ package to our local package list in +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Build again: + +code{ + +# lb build + +}code + +Test, and when you're satisfied, commit the next revision: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Of course, more complicated changes to the configuration are possible, +perhaps adding files in subdirectories of #{config/}#. When you commit new +revisions, just take care not to hand edit or commit the top-level files in +#{config}# containing #{LB_*}# variables, as these are build products, too, +and are always cleaned up by #{lb clean}# and re-created with #{lb config}# +via their respective #{auto}# scripts. + +We've come to the end of our tutorial series. While many more kinds of +customization are possible, even just using the few features explored in +these simple examples, an almost infinite variety of different images can be +created. The remaining examples in this section cover several other use +cases drawn from the collected experiences of users of live systems. + +2~ A VNC Kiosk Client + +*{Use case:}* Create an image with live-build to boot directly to a VNC server. + +Make a build directory and create an skeletal configuration inside it, +disabling recommends to make a minimal system. And then create two initial +package lists: the first one generated with a script provided by live-build +named #{Packages}# (see {Generated package lists}#generated-package-lists), +and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and +/{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you +may need to re-add some recommended packages to make your image work +properly. + +An easy way to list recommends is using /{apt-cache}/. For example: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +In this example we found out that we had to re-include several packages +recommended by live-config and live-boot: #{user-setup}# to make autologin +work and #{sudo}# as an essential program to shutdown the system. Besides, +it could be handy to add #{live-tools}# to be able to copy the image to RAM +and #{eject}# to eventually eject the live medium. So: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# +and put a custom #{.xsession}# in it for the default user that will launch +/{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a +server at #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Build the image: + +code{ + + # lb build + +}code + +Enjoy. + +2~ A base image for a 128MB USB key + +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. + +When optimizing an image to fit a certain media size, you need to understand +the tradeoffs you are making between size and functionality. In this +example, we trim only so much as to make room for additional material within +a 128MB media size, but without doing anything to destroy the integrity of +the packages contained within, such as the purging of locale data via the +/{localepurge}/ package, or other such "intrusive" optimizations. Of +particular note, we use #{--debootstrap-options}# to create a minimal system +from scratch. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +To make the image work properly, we must re-add, at least, two recommended +packages which are left out by the #{--apt-recommends false}# option. See +{Tweaking APT to save space}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Now, build the image in the usual way: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration +produced a 110MB image. This compares favourably with the 192MB image +produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount +of space, the tradeoff being that you need to do an #{apt-get update}# +before using /{apt}/ in the live system. Dropping recommended packages with +#{--apt-recommends false}# saves some additional space, at the expense of +omitting some packages you might otherwise expect to be +there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal +system from the start. Not automatically including firmware packages with +#{--firmware-chroot false}# saves some space too. And finally, #{--memtest +none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ A localized GNOME desktop and installer + +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. + +We want to make an iso-hybrid image for i386 architecture using our +preferred desktop, in this case GNOME, containing all of the same packages +that would be installed by the standard Debian installer for GNOME. + +Our initial problem is the discovery of the names of the appropriate +language tasks. Currently, live-build cannot help with this. While we might +get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, +which can be used to dig it out of the task descriptions in tasksel-data, so +to prepare, make sure you have both of those things: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Now we can search for the appropriate tasks, first with: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +By this command, we discover the task is called, plainly enough, german. Now +to find the related tasks: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +At boot time we will generate the *{de_CH.UTF-8}* locale and select the +*{ch}* keyboard layout. Now let's put the pieces together. Recalling from +{Using metapackages}#using-metapackages that task metapackages are prefixed +#{task-}#, we just specify these language boot parameters, then add standard +priority packages and all our discovered task metapackages to our package +list as follows: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to +launch the installer from the live desktop. The #{586}# kernel flavour, +which is currently necessary for the launcher to work properly, will be +included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/de/live-manual.ssm new file mode 100644 index 0000000..ba983b4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Live Systems Handbuch" + +creator: + author: "Live Systems Projekt <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." + +date: + published: "2015-08-23" + +publisher: "Live Systems Projekt <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +#bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ Über Live Systeme + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Benutzer + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Projekt + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Beispiele + +<< examples.ssi + +:B~ Anhang + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/de/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/de/project_bugs.ssi new file mode 100644 index 0000000..76a0eba --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/project_bugs.ssi @@ -0,0 +1,206 @@ +:B~ Reporting bugs + +1~bugs Reporting bugs + +Live systems are far from being perfect, but we want to make it as close as +possible to perfect - with your help. Do not hesitate to report a bug. It is +better to fill a report twice than never. However, this chapter includes +recommendations on how to file good bug reports. + +For the impatient: + +_* Always check first the image status updates on our homepage at +http://live-systems.org/ for known issues. + +_* Before submitting a bug report always try to reproduce the bug with the +*{most recent versions}* of the branch of live-build, live-boot, live-config +and live-tools that you're using (like the newest 4.x version of live-build +if you're using live-build 4). + +_* Try to give *{as specific information as possible}* about the bug. This +includes (at least) the version of live-build, live-boot, live-config, and +live-tools used and the distribution of the live system you are building. + +2~ Known issues + +Since Debian *{testing}* and Debian *{unstable}* distributions are moving +targets, when you specify either of them as the target system distribution, +a successful build may not always be possible. + +% FIXME: + +If this causes too much difficulty for you, do not build a system based on +*{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always +defaults to the *{stable}* release. + +Currently known issues are listed under the section 'status' on our homepage +at http://live-systems.org/. + +It is out of the scope of this manual to train you to correctly identify and +fix problems in packages of the development distributions, however, there +are two things you can always try: If a build fails when the target +distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work +either, revert to *{testing}* and pin the newer version of the failing +package from *{unstable}* (see {APT pinning}#apt-pinning for details). + +2~ Rebuild from scratch + +To ensure that a particular bug is not caused by an uncleanly built system, +please always rebuild the whole live system from scratch to see if the bug +is reproducible. + +2~ Use up-to-date packages + +Using outdated packages can cause significant problems when trying to +reproduce (and ultimately fix) your problem. Make sure your build system is +up-to-date and any packages included in your image are up-to-date as well. + +2~collect-information Collect information + +Please provide enough information with your report. Include, at least, the +exact version of live-build where the bug is encountered and the steps to +reproduce it. Please use your common sense and provide any other relevant +information if you think that it might help in solving the problem. + +To make the most out of your bug report, we require at least the following +information: + +_* Architecture of the host system + +_* Distribution of the host system + +_* Version of live-build on the host system + +_* Version of /{debootstrap}/ on the host system + +_* Architecture of the live system + +_* Distribution of the live system + +_* Version of live-boot on the live system + +_* Version of live-config on the live system + +_* Version of live-tools on the live system + +You can generate a log of the build process by using the #{tee}# command. We +recommend doing this automatically with an #{auto/build}# script (see +{Managing a configuration}#managing-a-configuration for details). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +At boot time, live-boot and live-config store their logfiles in +#{/var/log/live/}#. Check them for error messages. + +Additionally, to rule out other errors, it is always a good idea to tar up +your #{config/}# directory and upload it somewhere (do *{not}* send it as an +attachment to the mailing list), so that we can try to reproduce the errors +you encountered. If this is difficult (e.g. due to size) you can use the +output of #{lb config --dump}# which produces a summary of your config tree +(i.e. lists files in subdirectories of #{config/}# but does not include +them). + +Remember to send in any logs that were produced with English locale +settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or +#{LC_ALL=en_US}#. + +2~ Isolate the failing case if possible + +If possible, isolate the failing case to the smallest possible change that +breaks. It is not always easy to do this so if you cannot manage it for your +report, do not worry. However, if you plan your development cycle well, +using small enough change sets per iteration, you may be able to isolate the +problem by constructing a simpler 'base' configuration that closely matches +your actual configuration plus just the broken change set added to it. If +you have a hard time sorting out which of your changes broke, it may be that +you are including too much in each change set and should develop in smaller +increments. + +2~ Use the correct package to report the bug against + +If you do not know what component is responsible for the bug or if the bug +is a general bug concerning live systems, you can fill a bug against the +debian-live pseudo-package. + +However, we would appreciate it if you try to narrow it down according to +where the bug appears. + +3~ At build time while bootstrapping + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a +bug appears here, check if the error is related to a specific Debian package +(most likely), or if it is related to the bootstrapping tool itself. + +In both cases, this is not a bug in the live system, but rather in Debian +itself and probably we cannot fix it directly. Please report such a bug +against the bootstrapping tool or the failing package. + +3~ At build time while installing packages + +live-build installs additional packages from the Debian archive and +depending on the Debian distribution used and the daily archive state, it +can fail. If a bug appears here, check if the error is also reproducible on +a normal system. + +If this is the case, this is not a bug in the live system, but rather in +Debian - please report it against the failing package. Running +/{debootstrap}/ separately from the Live system build or running #{lb +bootstrap --debug}# will give you more information. + +Also, if you are using a local mirror and/or any sort of proxy and you are +experiencing a problem, please always reproduce it first by bootstrapping +from an official mirror. + +3~ At boot time + +If your image does not boot, please report it to the mailing list together +with the information requested in {Collect +information}#collect-information. Do not forget to mention, how/when the +image failed exactly, whether using virtualization or real hardware. If you +are using a virtualization technology of any kind, please always run it on +real hardware before reporting a bug. Providing a screenshot of the failure +is also very helpful. + +3~ At run time + +If a package was successfully installed, but fails while actually running +the Live system, this is probably a bug in the live system. However: + +2~ Do the research + +Before filing the bug, please search the web for the particular error +message or symptom you are getting. As it is highly unlikely that you are +the only person experiencing a particular problem. There is always a chance +that it has been discussed elsewhere and a possible solution, patch, or +workaround has been proposed. + +You should pay particular attention to the live systems mailing list, as +well as the homepage, as these are likely to contain the most up-to-date +information. If such information exists, always include the references to it +in your bug report. + +In addition, you should check the current bug lists for live-build, +live-boot, live-config and live-tools to see whether something similar has +already been reported. + +2~ Where to report bugs + +The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For +information on how to use the system, please see +https://bugs.debian.org/. You can also submit the bugs by using the +#{reportbug}# command from the package with the same name. + +In general, you should report build time errors against the live-build +package, boot time errors against live-boot, and run time errors against +live-config. If you are unsure of which package is appropriate or need more +help before submitting a bug report, please report it against the +debian-live pseudo-package. We will then take care about it and reassign it +where appropriate. + +Please note that bugs found in distributions derived from Debian (such as +Ubuntu and others) should *{not}* be reported to the Debian BTS unless they +can be also reproduced on a Debian system using official Debian packages. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/de/project_coding-style.ssi new file mode 100644 index 0000000..2adba20 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/project_coding-style.ssi @@ -0,0 +1,149 @@ +:B~ Coding Style + +1~coding-style Coding Style + +This chapter documents the coding style used in live systems. + +2~ Compatibility + +_* Don't use syntax or semantics that are unique to the Bash shell. For +example, the use of array constructs. + +_* Only use the POSIX subset - for example, use $(foo) over `foo`. + +_* You can check your scripts with 'sh -n' and 'checkbashisms'. + +_* Make sure all shell code runs with 'set -e'. + +2~ Indenting + +_* Always use tabs over spaces. + +2~ Wrapping + +_* Generally, lines are 80 chars at maximum. + +_* Use the "Linux style" of line breaks: + +Bad: + +code{ + + if foo; then + bar + fi + +}code + +Good: + +code{ + + if foo + then + bar + fi + +}code + +_* The same holds for functions: + +Bad: + +code{ + + Foo () { + bar + } + +}code + +Good: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Variables are always in capital letters. + +_* Variables used in live-build always start with #{LB_}# prefix. + +_* Internal temporary variables in live-build should start with the +#{\_LB_}# prefix. + +_* Local variables start with live-build #{\_\_LB_}# prefix. + +_* Variables in connection to a boot parameter in live-config start with +#{LIVE_}#. + +_* All other variables in live-config start with #{_}# prefix. + +_* Use braces around variables; e.g. write #{${FOO}}# instead of #{$FOO}#. + +_* Always protect variables with quotes to respect potential whitespaces: +write #{"${FOO}"}# not #{${FOO}}#. + +_* For consistency reasons, always use quotes when assigning values to +variables: + +Bad: + +code{ + + FOO=bar + +}code + +Good: + +code{ + + FOO="bar" + +}code + +_* If multiple variables are used, quote the full expression: + +Bad: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Good: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscellaneous + +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, +e.g. "#{sed -e 's|foo|bar|'}#" (without ""). + +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" +"#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test +-x /bin/foo; ...}#". + +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and +faster in execution. + +_* Use capitalized names for functions to limit messing with the users +environment. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/de/project_contributing.ssi new file mode 100644 index 0000000..8990f99 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/project_contributing.ssi @@ -0,0 +1,114 @@ +:B~ Contributing to the project + +1~contributing-to-project Contributing to the project + +When submitting a contribution, please clearly identify its copyright holder +and include any applicable licensing statement. Note that to be accepted, +the contribution must be licensed under the same license as the rest of the +documents, namely, GPL version 3 or later. + +Contributions to the project, such as translations and patches, are greatly +welcome. Anyone can directly commit to the repositories, however, we ask you +to send bigger changes to the mailing list to discuss them first. See the +section {Contact}#contact for more information. + +The ${project} uses Git as version control system and source code +management. As explained in {Git repositories}#git-repositories there are +two main development branches: *{debian}* and *{debian-next}*. Everybody can +commit to the debian-next branches of the live-boot, live-build, +live-config, live-images, live-manual and live-tools repositories. + +However, there are certain restrictions. The server will reject: + +_* Non fast-forward pushes. + +_* Merge commits. + +_* Adding or removing tags or branches. + +Even though all commits might be revised, we ask you to use your common +sense and make good commits with good commit messages. + +_* Write commit messages that consist of complete, meaningful sentences in +English, starting with a capital letter and ending with a full +stop. Usually, these will start with the form +"Fixing/Adding/Removing/Correcting/Translating/...". + +_* Write good commit messages. The first line must be an accurate summary of +the contents of the commit which will be included in the changelog. If you +need to make some further explanations, write them below leaving a blank +line after the first one and then another blank line after each +paragraph. Lines of paragraphs should not exceed 80 characters in length. + +_* Commit atomically, this is to say, do not mix unrelated things in the +same commit. Make one different commit for each change you make. + +2~ Making changes + +In order to push to the repositories, you must follow the following +procedure. Here we use live-manual as an example so replace it with the name +of the repository you want to work with. For detailed information on how to +edit live-manual see {Contributing to this document}#how-to-contribute. + +_* Fetch the public commit key: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Add the following section to your openssh-client config: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Check out a clone of live-manual through ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Make sure you have Git author and email set: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Important:}* Remember that you should commit any changes on the *{debian-next}* branch. + +_* Make your changes. In this example you would first write a new section +dealing with applying patches and then prepare to commit adding the files +and writing your commit message like this: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Push the commit to the server: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/de/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/de/project_git.ssi new file mode 100644 index 0000000..fd15acd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/project_git.ssi @@ -0,0 +1,87 @@ +:B~ Git repositories + +1~git-repositories Git repositories + +The list of all the available repositories of the ${project} can be found at +http://live-systems.org/gitweb/. The project's git URLs have the form: +#{protocol://live-systems.org/git/repository}#. Thus, in order to clone +live-manual read-only, launch: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +The cloning addresses with write permission have the form: +#{git@live-systems.org:/repository}#. + +So, again, to clone live-manual over ssh you must type: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +The git tree is made up of several different branches. The *{debian}* and +the *{debian-next}* branches are particularly noteworthy because they +contain the actual work that will eventually be included in each new +release. + +After cloning any of the existing repositories, you will be on the +*{debian}* branch. This is appropriate to take a look at the state of the +project's latest release but before starting work it is crucial to switch to +the *{debian-next}* branch. To do so: + +code{ + + $ git checkout debian-next + +}code + +The *{debian-next}* branch, which is not always fast-forward, is where all +the changes are committed first before being merged into the *{debian}* +branch. To make an analogy, it is like a testing ground. If you are working +on this branch and need to pull, you will have to do a #{git pull --rebase}# +so that your local modifications are staged while pulling from the server +and then your changes will be put on top of it all. + +2~ Handling multiple repositories + +If you intend to clone several of the live systems repositories and want to +switch to the *{debian-next}* branch right away to check the latest code, +write a patch or contribute with a translation you ought to know that the +git server provides a #{mrconfig}# file to ease the handling of multiple +repositories. In order to use it you need to install the /{mr}/ package and +after that, launch: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +This command will automatically clone and checkout to the *{debian-next}* +branch the development repositories of the Debian packages produced by the +project. These include, among others, the live-images repository, which +contains the configurations used for the prebuilt images that the project +publishes for general use. For more information on how to use this +repository, see {Clone a configuration published via +Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/de/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/de/project_procedures.ssi new file mode 100644 index 0000000..784e0e6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/project_procedures.ssi @@ -0,0 +1,99 @@ +:B~ Projektabläufe + +1~procedures Procedures + +This chapter documents the procedures within the ${project} for various +tasks that need cooperation with other teams in Debian. + +2~ Major Releases + +Releasing a new stable major version of Debian includes a lot of different +teams working together to make it happen. At some point, the Live team comes +in and builds live system images. The requirements to do this are: + +_* A mirror containing the released versions for the debian and +debian-security archives which the debian-live buildd can access. + +_* The names of the image need to be known +(e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* The data from debian-cd needs to be synced (udeb exclude lists). + +_* Images are built and mirrored on cdimage.debian.org. + +2~ Point Releases + +_* Again, we need updated mirrors of debian and debian-security. + +_* Images are built and mirrored on cdimage.debian.org. + +_* Send announcement mail. + +3~ Last Point Release of a Debian Release + +Remember to adjust both chroot and binary mirrors when building the last set +of images for a Debian release after it has been moved away from +ftp.debian.org to archive.debian.org. That way, old prebuilt live images are +still useful without user modifications. + +3~ Point release announcement template + +An announcement mail for point releases can be generated using the template +below and the following command: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Please check the mail carefully before sending and pass it to others for +proof-reading. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_basics.ssi new file mode 100644 index 0000000..92371a8 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_basics.ssi @@ -0,0 +1,626 @@ +:B~ The basics + +1~the-basics The basics + +This chapter contains a brief overview of the build process and instructions +for using the three most commonly used image types. The most versatile image +type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or +USB portable storage device. In certain special cases, as explained later, +the #{hdd}# type may be more suitable. The chapter includes detailed +instructions for building and using a #{netboot}# type image, which is a bit +more involved due to the setup required on the server. This is an slightly +advanced topic for anyone who is not already familiar with netbooting, but +it is included here because once the setup is done, it is a very convenient +way to test and deploy images for booting on the local network without the +hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting +which is, perhaps, the easiest way of using different images for different +purposes, switching from one to the other as needed using the internet as a +means. + +Throughout the chapter, we will often refer to the default filenames +produced by live-build. If you are {downloading a prebuilt +image}#downloading-prebuilt-images instead, the actual filenames may vary. + +2~what-is-live What is a live system? + +A live system usually means an operating system booted on a computer from a +removable medium, such as a CD-ROM or USB stick, or from a network, ready to +use without any installation on the usual drive(s), with auto-configuration +done at run time (see {Terms}#terms). + +With live systems, it's an operating system, built for one of the supported +architectures (currently amd64 and i386). It is made from the following +parts: + +_* *{Linux kernel image}*, usually named #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux +boot, containing modules possibly needed to mount the System image and some +scripts to do it. + +_* *{System image}*: The operating system's filesystem image. Usually, a +SquashFS compressed filesystem is used to minimize the live system image +size. Note that it is read-only. So, during boot the live system will use a +RAM disk and 'union' mechanism to enable writing files within the running +system. However, all modifications will be lost upon shutdown unless +optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen +medium, possibly presenting a prompt or menu to allow selection of +options/configuration. It loads the Linux kernel and its initrd to run with +an associated system filesystem. Different solutions can be used, depending +on the target medium and format of the filesystem containing the previously +mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, +syslinux for HDD or USB drive booting from a VFAT partition, extlinux for +ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 +partitions, etc. + +You can use live-build to build the system image from your specifications, +set up a Linux kernel, its initrd, and a bootloader to run them, all in one +medium-dependant format (ISO9660 image, disk image, etc.). + +2~downloading-prebuilt-images Downloading prebuilt images + +While the focus of this manual is developing and building your own live +images, you may simply wish to try one of our prebuilt images, either as an +introduction to their use or instead of building your own. These images are +built using our {live-images git repository}#clone-configuration-via-git and +official stable releases are published at +https://www.debian.org/CD/live/. In addition, older and upcoming releases, +and unofficial images containing non-free firmware and drivers are available +at http://live-systems.org/cdimage/release/. + +2~using-web-builder Using the web live image builder + +As a service to the community, we run a web-based live image builder service +at http://live-systems.org/build/. This site is maintained on a best effort +basis. That is, although we strive to keep it up-to-date and operational at +all times, and do issue notices for significant operational outages, we +cannot guarantee 100% availability or fast image building, and the service +may occasionally have issues that take some time to resolve. If you have +problems or questions about the service, please {contact us}#contact, +providing us with the link to your build. + +3~ Web builder usage and caveats + +The web interface currently makes no provision to prevent the use of invalid +combinations of options, and in particular, where changing an option would +normally (i.e. using live-build directly) change defaults of other options +listed in the web form, the web builder does not change these defaults. Most +notably, if you change #{--architectures}# from the default #{i386}# to +#{amd64}#, you must change the corresponding option #{--linux-flavours}# +from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for +the version of live-build installed on the web builder for more details. The +version number of live-build is listed at the bottom of the web builder +page. + +The time estimate given by the web builder is a crude estimate only and may +not reflect how long your build actually takes. Nor is the estimate updated +once it is displayed. Please be patient. Do not refresh the page you land on +after submitting the build, as this will resubmit a new build with the same +parameters. You should {contact us}#contact if you don't receive +notification of your build only once you are certain you've waited long +enough and verified the notification e-mail did not get caught by your own +e-mail spam filter. + +The web builder is limited in the kinds of images it can build. This keeps +it simple and efficient to use and maintain. If you would like to make +customizations that are not provided for by the web interface, the rest of +this manual explains how to build your own images using live-build. + +2~building-iso-hybrid First steps: building an ISO hybrid image + +Regardless of the image type, you will need to perform the same basic steps +to build an image each time. As a first example, create a build directory, +change to that directory and then execute the following sequence of +live-build commands to create a basic ISO hybrid image containing a default +live system without X.org. It is suitable for burning to CD or DVD media, +and also to copy onto a USB stick. + +The name of the working directory is absolutely up to you, but if you take a +look at the examples used throughout live-manual, it is a good idea to use a +name that helps you identify the image you are working with in each +directory, especially if you are working or experimenting with different +image types. In this case you are going to build a default system so let's +call it, for example, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy +in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their +various options will be used. See {The lb config command}#lb-config for more +details. + +Now that the "config/" hierarchy exists, build the image with the #{lb +build}# command: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and +your network connection. When it is complete, there should be a +#{live-image-i386.hybrid.iso}# image file, ready to use, in the current +directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Using an ISO hybrid live image + +After either building or downloading an ISO hybrid image, which can be +obtained at https://www.debian.org/CD/live/, the usual next step is to +prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or +a USB stick. + +3~burning-iso-image Burning an ISO image to a physical medium + +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the +command-line to burn the image. For instance: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copying an ISO hybrid image to a USB stick + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick +with the #{cp}# program or an equivalent. Plug in a USB stick with a size +large enough for your image file and determine which device it is, which we +hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, +such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find +the right device name by looking in #{dmesg}#'s output after plugging in the +stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# +command to copy the image to the stick. *{This will definitely overwrite +any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Using the space left on a USB stick + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first +partition on the device will be filled up by the live system. To use the +remaining free space, use a partitioning tool such as /{gparted}/ or +/{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +After the partition is created, where #{${PARTITION}}# is the name of the +partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One +possible choice would be ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-medium Booting the live medium + +The first time you boot your live medium, whether CD, DVD, USB key, or PXE +boot, some setup in your computer's BIOS may be needed first. Since BIOSes +vary greatly in features and key bindings, we cannot get into the topic in +depth here. Some BIOSes provide a key to bring up a menu of boot devices at +boot time, which is the easiest way if it is available on your +system. Otherwise, you need to enter the BIOS configuration menu and change +the boot order to place the boot device for the live system before your +normal boot device. + +Once you've booted the medium, you are presented with a boot menu. If you +just press enter here, the system will boot using the default entry, +#{Live}# and default options. For more information about boot options, see +the "help" entry in the menu and also the live-boot and live-config man +pages found within the live system. + +Assuming you've selected #{Live}# and booted a default desktop live image, +after the boot messages scroll by, you should be automatically logged into +the #{user}# account and see a desktop, ready to use. If you have booted a +console-only image, such as a #{standard}# flavour {prebuilt +image}#downloading-prebuilt-images, you should be automatically logged in on +the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Using a virtual machine for testing + +It can be a great time-saver for the development of live images to run them +in a virtual machine (VM). This is not without its caveats: + +_* Running a VM requires enough RAM for both the guest OS and the host and a +CPU with hardware support for virtualization is recommended. + +_* There are some inherent limitations to running on a VM, e.g. poor video +performance, limited choice of emulated hardware. + +_* When developing for specific hardware, there is no substitute for running +on the hardware itself. + +_* Occasionally there are bugs that relate only to running in a VM. When in +doubt, test your image directly on the hardware. + +Provided you can work within these constraints, survey the available VM +software and choose one that is suitable for your needs. + +3~testing-iso-with-qemu Testing an ISO image with QEMU + +The most versatile VM in Debian is QEMU. If your processor has hardware +support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ +package description briefly lists the requirements. + +First, install /{qemu-kvm}/ if your processor supports it. If not, install +/{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in +the following examples. The /{qemu-utils}/ package is also valuable for +creating virtual disk images with #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Booting an ISO image is simple: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +See the man pages for more details. + +3~testing-iso-with-virtualbox Testing an ISO image with VirtualBox + +In order to test the ISO with /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use +#{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +In order to make the dkms package work, also the kernel headers for the +kernel flavour used in your image need to be installed. Instead of manually +listing the correct /{linux-headers}/ package in above created package list, +the selection of the right package can be done automatically by live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Building and using an HDD image + +Building an HDD image is similar to an ISO hybrid one in all respects except +you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# +which cannot be burnt to optical media. It is suitable for booting from USB +sticks, USB hard drives, and various other portable storage +devices. Normally, an ISO hybrid image can be used for this purpose instead, +but if you have a BIOS which does not handle hybrid images properly, you +need an HDD image. + +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Run the #{lb config}# command as before, except this time specifying the HDD +image type: + +code{ + + $ lb config -b hdd + +}code + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in +the current directory. + +The generated binary image contains a VFAT partition and the syslinux +bootloader, ready to be directly written on a USB device. Once again, using +an HDD image is just like using an ISO hybrid one on USB. Follow the +instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except +use the filename #{live-image-i386.img}# instead of +#{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described +above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run +#{kvm}# or #{qemu}#, depending on which version your host system needs, +specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Building a netboot image + +The following sequence of commands will create a basic netboot image +containing a default live system without X.org. It is suitable for booting +over the network. + +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean +up the necessary stages. The cause for this is that in netboot setups, a +different initramfs configuration needs to be used which live-build performs +automatically when building netboot images. Since the initramfs creation +belongs to the chroot stage, switching to netboot in an existing build +directory means to rebuild the chroot stage too. Therefore, #{lb clean}# +(which will remove the chroot stage, too) needs to be used. + +Run the #{lb config}# command as follows to configure your image for +netbooting: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +In contrast with the ISO and HDD images, netbooting does not, itself, serve +the filesystem image to the client, so the files must be served via +NFS. Different network filesystems can be chosen through lb config. The +#{--net-root-path}# and #{--net-root-server}# options specify the location +and server, respectively, of the NFS server where the filesystem image will +be located at boot time. Make sure these are set to suitable values for your +network and server. + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +In a network boot, the client runs a small piece of software which usually +resides on the EPROM of the Ethernet card. This program sends a DHCP request +to get an IP address and information about what to do next. Typically, the +next step is getting a higher level bootloader via the TFTP protocol. That +could be pxelinux, GRUB, or even boot directly to an operating system like +Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# +archive in the #{/srv/debian-live}# directory, you'll find the filesystem +image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux +bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the +DHCP server, the TFTP server and the NFS server. + +3~ DHCP server + +We must configure our network's DHCP server to be sure to give an IP address +to the netbooting client system, and to advertise the location of the PXE +bootloader. + +Here is an example for inspiration, written for the ISC DHCP server +#{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ TFTP server + +This serves the kernel and initial ramdisk to the system at run time. + +You should install the /{tftpd-hpa}/ package. It can serve all files +contained inside a root directory, usually #{/srv/tftp}#. To let it serve +files inside #{/srv/debian-live/tftpboot}#, run as root the following +command: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +and fill in the new tftp server directory when being asked about it. + +3~ NFS server + +Once the guest computer has downloaded and booted a Linux kernel and loaded +its initrd, it will try to mount the Live filesystem image through a NFS +server. + +You need to install the /{nfs-kernel-server}/ package. + +Then, make the filesystem image available through NFS by adding a line like +the following to #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +and tell the NFS server about this new export with the following command: + +code{ + + # exportfs -rv + +}code + +Setting up these three services can be a little tricky. You might need some +patience to get all of them working together. For more information, see the +syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the +Debian Installer Manual's TFTP Net Booting section at +http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, +as their processes are very similar. + +3~ Netboot testing HowTo + +Netboot image creation is made easy with live-build, but testing the images +on physical machines can be really time consuming. + +To make our life easier, we can use virtualization. + +3~ Qemu + +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Edit #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Get, or build a #{grub-floppy-netboot}#. + +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using +the internet as a means. The requirements for webbooting are very few. On +the one hand, you need a medium with a bootloader, an initial ramdisk and a +kernel. On the other hand, a web server to store the squashfs files which +contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which +are available on the project's homepage at http://live-systems.org/. Using +prebuilt images would be handy for doing initial testing until one can fine +tune their own needs. If you have built a live image you will find the files +needed for webbooting in the build directory under #{binary/live/}#. The +files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso +image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific +case, it would be #{/mnt/live/}#. This method has the disadvantage that you +need to be root to be able to mount the image. However, it has the advantage +that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image +and uploading it to the web server at the same time, is using the midnight +commander or /{mc}/. If you have the /{genisoimage}/ package installed, the +two-pane file manager allows you to browse the contents of an iso file in +one pane and upload the files via ftp in the other pane. Even though this +method requires manual work, it does not require root privileges. + +3~ Booting webboot images + +While some users will prefer virtualization to test webbooting, we refer to +real hardware here to match the following possible use case which should +only be considered as an example. + +In order to boot a webboot image it is enough to have the components +mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a +directory named #{live/}# and install syslinux as bootloader. Then boot from +the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot +options. live-boot will retrieve the squashfs file and store it into +ram. This way, it is possible to use the downloaded compressed filesystem as +a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-binary.ssi new file mode 100644 index 0000000..aa7929a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-binary.ssi @@ -0,0 +1,62 @@ +:B~ Customizing the binary image + +1~customizing-binary Customizing the binary image + +2~ Bootloaders + +live-build uses /{syslinux}/ and some of its derivatives (depending on the +image type) as bootloaders by default. They can be easily customized to suit +your needs. + +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# +into #{config/bootloaders}# and edit the files in there. If you do not want +to bother modifying all supported bootloader configurations, only providing +a local customized copy of one of the bootloaders, e.g. *{isolinux}* in +#{config/bootloaders/isolinux}# is enough too, depending on your use case. + +When modifying one of the default themes, if you want to use a personalized +background image that will be displayed together with the boot menu, add a +splash.png picture of 640x480 pixels. Then, remove the splash.svg file. + +There are many possibilities when it comes to making changes. For instance, +syslinux derivatives are configured by default with a timeout of 0 (zero) +which means that they will pause indefinitely at their splash screen until +you press a key. + +To modify the boot timeout of a default #{iso-hybrid}# image just edit a +default *{isolinux.cfg}* file specifying the timeout in units of 1/10 +seconds. A modified *{isolinux.cfg}* to boot after five seconds would be +similar to this: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ ISO metadata + +When creating an ISO9660 binary image, you can use the following options to +add various textual metadata for your image. This can help you easily +identify the version or configuration of an image without booting it. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the +application that will be on the image. The maximum length for this field is +128 characters. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the +preparer of the image, usually with some contact details. The default for +this option is the live-build version you are using, which may help with +debugging later. The maximum length for this field is 128 characters. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the +publisher of the image, usually with some contact details. The maximum +length for this field is 128 characters. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of +the image. This is used as a user-visible label on some platforms such as +Windows and Apple Mac OS. The maximum length for this field is 32 +characters. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-contents.ssi new file mode 100644 index 0000000..821fea4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-contents.ssi @@ -0,0 +1,135 @@ +:B~ Customizing contents + +1~customizing-contents Customizing contents + +This chapter discusses fine-tuning customization of the live system contents +beyond merely choosing which packages to include. Includes allow you to add +or replace arbitrary files in your live system image, hooks allow you to +execute arbitrary commands at different stages of the build and at boot +time, and preseeding allows you to configure packages when they are +installed by supplying answers to debconf questions. + +2~includes Includes + +While ideally a live system would include files entirely provided by +unmodified packages, it is sometimes convenient to provide or modify some +content by means of files. Using includes, it is possible to add (or +replace) arbitrary files in your live system image. live-build provides two +mechanisms for using them: + +_* Chroot local includes: These allow you to add or replace files to the +chroot/Live filesystem. Please see {Live/chroot local +includes}#live-chroot-local-includes for more information. + +_* Binary local includes: These allow you to add or replace files in the +binary image. Please see {Binary local includes}#binary-local-includes for +more information. + +Please see {Terms}#terms for more information about the distinction between +the "Live" and "binary" images. + +3~live-chroot-local-includes Live/chroot local includes + +Chroot local includes can be used to add or replace files in the chroot/Live +filesystem so that they may be used in the Live system. A typical use is to +populate the skeleton user directory (#{/etc/skel}#) used by the Live system +to create the live user's home directory. Another is to supply configuration +files that can be simply added or replaced in the image without processing; +see {Live/chroot local hooks}#live-chroot-local-hooks if processing is +needed. + +To include files, simply add them to your #{config/includes.chroot}# +directory. This directory corresponds to the root directory #{/}# of the +live system. For example, to add a file #{/var/www/index.html}# in the live +system, use: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Your configuration will then have the following layout: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Chroot local includes are installed after package installation so that files +installed by packages are overwritten. + +3~binary-local-includes Binary local includes + +To include material such as documentation or videos on the medium filesystem +so that it is accessible immediately upon insertion of the medium without +booting the Live system, you can use binary local includes. This works in a +similar fashion to chroot local includes. For example, suppose the files +#{~/video_demo.*}# are demo videos of the live system described by and +linked to by an HTML index page. Simply copy the material to +#{config/includes.binary/}# as follows: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +These files will now appear in the root directory of the live medium. + +2~hooks Hooks + +Hooks allow commands to be performed in the chroot and binary stages of the +build in order to customize the image. + +3~live-chroot-local-hooks Live/chroot local hooks + +To run commands in the chroot stage, create a hook script with a +#{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run in the chroot after the rest of your chroot +configuration has been applied, so remember to ensure your configuration +includes all packages and files your hook needs in order to run. See the +example chroot hook scripts for various common chroot customization tasks +provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy +or symlink to use them in your own configuration. + +3~boot-time-hooks Boot-time hooks + +To execute commands at boot time, you can supply live-config hooks as +explained in the "Customization" section of its man page. Examine +live-config's own hooks provided in #{/lib/live/config/}#, noting the +sequence numbers. Then provide your own hook prefixed with an appropriate +sequence number, either as a chroot local include in +#{config/includes.chroot/lib/live/config/}#, or as a custom package as +discussed in {Installing modified or third-party +packages}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +To run commands in the binary stage, create a hook script with a +#{.hook.binary}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run after all other binary commands are run, but +before binary_checksums, the very last binary command. The commands in your +hook do not run in the chroot, so take care to not modify any files outside +of the build tree, or you may damage your build system! See the example +binary hook scripts for various common binary customization tasks provided +in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or +symlink to use them in your own configuration. + +2~ Preseeding Debconf questions + +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed +by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf +preseed files and are installed by live-build using +#{debconf-set-selections}# during the corresponding stage. + +For more information about debconf, please see #{debconf(7)}# in the +/{debconf}/ package. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-installer.ssi new file mode 100644 index 0000000..2f3a5a2 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-installer.ssi @@ -0,0 +1,86 @@ +:B~ Customizing Debian Installer + +1~customizing-installer Customizing Debian Installer + +Live system images can be integrated with Debian Installer. There are a +number of different types of installation, varying in what is included and +how the installer operates. + +Please note the careful use of capital letters when referring to the "Debian +Installer" in this section - when used like this we refer explicitly to the +official installer for the Debian system, not anything else. It is often +seen abbreviated to "d-i". + +2~ Types of Debian Installer + +The three main types of installer are: + +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". + +On such images, Debian is installed by fetching and installing .deb packages +using /{debootstrap}/, from local media or some network-based network, +resulting in a default Debian system being installed to the hard disk. + +This whole process can be preseeded and customized in a number of ways; see +the relevant pages in the Debian Installer manual for more information. Once +you have a working preseeding file, live-build can automatically put it in +the image and enable it for you. + +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. + +Installation will proceed in an identical fashion to the "normal" +installation described above, but at the actual package installation stage, +instead of using /{debootstrap}/ to fetch and install packages, the live +filesystem image is copied to the target. This is achieved with a special +udeb called live-installer. + +After this stage, the Debian Installer continues as normal, installing and +configuring items such as bootloaders and local users, etc. + +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. + +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. + +Note that by default, live-build does not include Debian Installer images in +the images, it needs to be specifically enabled with #{lb config}#. Also, +please note that for the "Desktop" installer to work, the kernel of the live +system must match the kernel #{d-i}# uses for the specified +architecture. For example: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Customizing Debian Installer by preseeding + +As described in the Debian Installer Manual, Appendix B at +https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a +way to set answers to questions asked during the installation process, +without having to manually enter the answers while the installation is +running. This makes it possible to fully automate most types of installation +and even offers some features not available during normal installations." +This kind of customization is best accomplished with live-build by placing +the configuration in a #{preseed.cfg}# file included in +#{config/includes.installer/}#. For example, to preseed setting the locale +to #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Customizing Debian Installer content + +For experimental or debugging purposes, you might want to include locally +built #{d-i}# component udeb packages. Place these in +#{config/packages.binary/}# to include them in the image. Additional or +replacement files and directories may be included in the installer initrd as +well, in a similar fashion to {Live/chroot local +includes}#live-chroot-local-includes, by placing the material in +#{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-overview.ssi new file mode 100644 index 0000000..54ab92c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-overview.ssi @@ -0,0 +1,75 @@ +:B~ Customizing contents + +1~customization-overview Customization overview + +This chapter gives an overview of the various ways in which you may +customize a live system. + +2~ Build time vs. boot time configuration + +Live system configuration options are divided into build-time options which +are options that are applied at build time and boot-time options which are +applied at boot time. Boot-time options are further divided into those +occurring early in the boot, applied by the live-boot package, and those +that happen later in the boot, applied by live-config. Any boot-time option +may be modified by the user by specifying it at the boot prompt. The image +may also be built with default boot parameters so users can normally just +boot directly to the live system without specifying any options when all of +the defaults are suitable. In particular, the argument to #{lb +--bootappend-live}# consists of any default kernel command line options for +the Live system, such as persistence, keyboard layouts, or timezone. See +{Customizing locale and language}#customizing-locale-and-language, for +example. + +Build-time configuration options are described in the #{lb config}# man +page. Boot-time options are described in the man pages for live-boot and +live-config. Although the live-boot and live-config packages are installed +within the live system you are building, it is recommended that you also +install them on your build system for easy reference when you are working on +your configuration. It is safe to do so, as none of the scripts contained +within them are executed unless the system is configured as a live system. + +2~stages-of-the-build Stages of the build + +The build process is divided into stages, with various customizations +applied in sequence in each. The first stage to run is the *{bootstrap}* +stage. This is the initial phase of populating the chroot directory with +packages to make a barebones Debian system. This is followed by the +*{chroot}* stage, which completes the construction of chroot directory, +populating it with all of the packages listed in the configuration, along +with any other materials. Most customization of content occurs in this +stage. The final stage of preparing the live image is the *{binary}* stage, +which builds a bootable image, using the contents of the chroot directory to +construct the root filesystem for the Live system, and including the +installer and any other additional material on the target medium outside of +the Live system's filesystem. After the live image is built, if enabled, the +source tarball is built in the *{source}* stage. + +Within each of these stages, there is a particular sequence in which +commands are applied. These are arranged in such a way as to ensure +customizations can be layered in a reasonable fashion. For example, within +the *{chroot}* stage, preseeds are applied before any packages are +installed, packages are installed before any locally included files are +copied, and hooks are run later, after all of the materials are in place. + +2~ Supplement lb config with files + +Although #{lb config}# creates a skeletal configuration in the #{config/}# +directory, to accomplish your goals, you may need to provide additional +files in subdirectories of #{config/}#. Depending on where the files are +stored in the configuration, they may be copied into the live system's +filesystem or into the binary image filesystem, or may provide build-time +configurations of the system that would be cumbersome to pass as +command-line options. You may include things such as custom lists of +packages, custom artwork, or hook scripts to run either at build time or at +boot time, boosting the already considerable flexibility of debian-live with +code of your own. + +2~ Customization tasks + +The following chapters are organized by the kinds of customization task +users typically perform: {Customizing package +installation}#customizing-package-installation, {Customizing +contents}#customizing-contents and {Customizing locale and +language}#customizing-locale-and-language cover just a few of the things you +might want to do. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-packages.ssi new file mode 100644 index 0000000..dd6bd88 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-packages.ssi @@ -0,0 +1,643 @@ +:B~ Customizing package installation + +1~customizing-package-installation Customizing package installation + +Perhaps the most basic customization of a live system is the selection of +packages to be included in the image. This chapter guides you through the +various build-time options to customize live-build's installation of +packages. The broadest choices influencing which packages are available to +install in the image are the distribution and archive areas. To ensure +decent download speeds, you should choose a nearby distribution mirror. You +can also add your own repositories for backports, experimental or custom +packages, or include packages directly as files. You can define lists of +packages, including metapackages which will install many related packages at +once, such as packages for a particular desktop or language. Finally, a +number of options give some control over /{apt}/, or if you prefer, +/{aptitude}/, at build time when packages are installed. You may find these +handy if you use a proxy, want to disable installation of recommended +packages to save space, or need to control which versions of packages are +installed via APT pinning, to name a few possibilities. + +2~ Package sources + +3~ Distribution, archive areas and mode + +The distribution you choose has the broadest impact on which packages are +available to include in your live image. Specify the codename, which +defaults to ${testing} for the ${testing} version of live-build. Any current +distribution carried in the archive may be specified by its codename +here. (See {Terms}#terms for more details.) The #{--distribution}# option +not only influences the source of packages within the archive, but also +instructs live-build to behave as needed to build each supported +distribution. For example, to build against the *{unstable}* release, sid, +specify: + +code{ + + $ lb config --distribution sid + +}code + +Within the distribution archive, archive areas are major divisions of the +archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only +#{main}# contains software that is part of the Debian distribution, hence +that is the default. One or more values may be specified, e.g. + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimental support is available for some Debian derivatives through a +#{--mode}# option. By default, this option is set to #{debian}# only if you +are building on a Debian or on an unknown system. If #{lb config}# is +invoked on any of the supported derivatives, it will default to create an +image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, +the distribution names and archive areas for the specified derivative are +supported instead of the ones for Debian. The mode also modifies live-build +behaviour to suit the derivatives. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Distribution mirrors + +The Debian archive is replicated across a large network of mirrors around +the world so that people in each region can choose a nearby mirror for best +download speed. Each of the #{--mirror-*}# options governs which +distribution mirror is used at various stages of the build. Recall from +{Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is +when the chroot is initially populated by /{debootstrap}/ with a minimal +system, and the *{chroot}* stage is when the chroot used to construct the +live system's filesystem is built. Thus, the corresponding mirror switches +are used for those stages, and later, in the *{binary}* stage, the +#{--mirror-binary}# and #{--mirror-binary-security}# values are used, +superseding any mirrors used in an earlier stage. + +3~distribution-mirrors-build-time Distribution mirrors used at build time + +To set the distribution mirrors used at build time to point at a local +mirror, it is sufficient to set #{--mirror-bootstrap}# and +#{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the +#{--mirror-bootstrap}# value. + +3~ Distribution mirrors used at run time + +The #{--mirror-binary*}# options govern the distribution mirrors placed in +the binary image. These may be used to install additional packages while +running the live system. The defaults employ #{httpredir.debian.org}#, a +service that chooses a geographically close mirror based, among other +things, on the user's IP family and the availability of the mirrors. This is +a suitable choice when you cannot predict which mirror will be best for all +of your users. Or you may specify your own values as shown in the example +below. An image built from this configuration would only be suitable for +users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Additional repositories + +You may add more repositories, broadening your package choices beyond what +is available in your target distribution. These may be, for example, for +backports, experimental or custom packages. To configure additional +repositories, create #{config/archives/your-repository.list.chroot}#, and/or +#{config/archives/your-repository.list.binary}# files. As with the +#{--mirror-*}# options, these govern the repositories used in the *{chroot}* +stage when building the image, and in the *{binary}* stage, i.e. for use +when running the live system. + +For example, #{config/archives/live.list.chroot}# allows you to install +packages from the debian-live snapshot repository at live system build time. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +If you add the same line to #{config/archives/live.list.binary}#, the +repository will be added to your live system's #{/etc/apt/sources.list.d/}# +directory. + +If such files exist, they will be picked up automatically. + +You should also put the GPG key used to sign the repository into +#{config/archives/your-repository.key.{binary,chroot}}# files. + +Should you need custom APT pinning, such APT preferences snippets can be +placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and +will be automatically added to your live system's +#{/etc/apt/preferences.d/}# directory. + +2~choosing-packages-to-install Choosing packages to install + +There are a number of ways to choose which packages live-build will install +in your image, covering a variety of different needs. You can simply name +individual packages to install in a package list. You can also use +metapackages in those lists, or select them using package control file +fields. And finally, you may place package files in your #{config/}# tree, +which is well suited to testing of new or experimental packages before they +are available from a repository. + +3~package-lists Package lists + +Package lists are a powerful way of expressing which packages should be +installed. The list syntax supports conditional sections which makes it easy +to build lists and adapt them for use in multiple configurations. Package +names may also be injected into the list using shell helpers at build time. + +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. + +3~using-metapackages Using metapackages + +The simplest way to populate your package list is to use a task metapackage +maintained by your distribution. For example: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# +2.x. Unlike predefined lists, task metapackages are not specific to the Live +System project. Instead, they are maintained by specialist working groups +within the distribution and therefore reflect the consensus of each group +about which packages best serve the needs of the intended users. They also +cover a much broader range of use cases than the predefined lists they +replace. + +All task metapackages are prefixed #{task-}#, so a quick way to determine +which are available (though it may contain a handful of false hits that +match the name but aren't metapackages) is to match on the package name +with: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +In addition to these, you will find other metapackages with various +purposes. Some are subsets of broader task packages, like #{gnome-core}#, +while others are individual specialized parts of a Debian Pure Blend, such +as the #{education-*}# metapackages. To list all metapackages in the +archive, install the #{debtags}# package and list all packages with the +#{role::metapackage}# tag as follows: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Local package lists + +Whether you list metapackages, individual packages, or a combination of +both, all local package lists are stored in #{config/package-lists/}#. Since +more than one list can be used, this lends itself well to modular +designs. For example, you may decide to devote one list to a particular +choice of desktop, another to a collection of related packages that might as +easily be used on top of a different desktop. This allows you to experiment +with different combinations of sets of packages with a minimum of fuss, +sharing common lists between different live image projects. + +Package lists that exist in this directory need to have a #{.list}# suffix +in order to be processed, and then an additional stage suffix, #{.chroot}# +or #{.binary}# to indicate which stage the list is for. + +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. + +3~ Local binary package lists + +To make a binary stage list, place a file suffixed with #{.list.binary}# in +#{config/package-lists/}#. These packages are not installed in the live +filesystem, but are included on the live medium under #{pool/}#. You would +typically use such a list with one of the non-live installer variants. As +mentioned above, if you want this list to be the same as your chroot stage +list, simply use the #{.list}# suffix by itself. + +3~generated-package-lists Generated package lists + +It sometimes happens that the best way to compose a list is to generate it +with a script. Any line starting with an exclamation point indicates a +command to be executed within the chroot when the image is built. For +example, one might include the line #{! grep-aptavail -n -sPackage +-FPriority standard | sort}# in a package list to produce a sorted list of +available packages with #{Priority: standard}#. + +In fact, selecting packages with the #{grep-aptavail}# command (from the +#{dctrl-tools}# package) is so useful that #{live-build}# provides a +#{Packages}# helper script as a convenience. This script takes two +arguments: #{field}# and #{pattern}#. Thus, you can create a list with the +following contents: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Using conditionals inside package lists + +Any of the live-build configuration variables stored in #{config/*}# (minus +the #{LB_}# prefix) may be used in conditional statements in package +lists. Generally, this means any #{lb config}# option uppercased and with +dashes changed to underscores. But in practice, it is only the ones that +influence package selection that make sense, such as #{DISTRIBUTION}#, +#{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. + +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is +specified: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +You may test for any one of a number of values, e.g. to install +/{memtest86+}/ if either #{--architectures i386}# or #{--architectures +amd64}# is specified: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +You may also test against variables that may contain more than one value, +e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified +via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +The nesting of conditionals is not supported. + +% FIXME: + +3~ Removing packages at install time + +You can list packages in files with #{.list.chroot_live}# and +#{.list.chroot_install}# suffixes inside the #{config/package-lists}# +directory. If both a live and an install list exist, the packages in the +#{.list.chroot_live}# list are removed with a hook after the installation +(if the user uses the installer). The packages in the +#{.list.chroot_install}# list are present both in the live system and in the +installed system. This is a special tweak for the installer and may be +useful if you have #{--debian-installer live}# set in your config, and wish +to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Desktop and language tasks + +Desktop and language tasks are special cases that need some extra planning +and configuration. Live images are different from Debian Installer images in +this respect. In the Debian Installer, if the medium was prepared for a +particular desktop environment flavour, the corresponding task will be +automatically installed. Thus, there are internal #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which +are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for +tasks for languages, but the user's language choice during the install +influences the selection of corresponding language tasks. + +When developing a desktop live image, the image typically boots directly to +a working desktop, the choices of both desktop and default language having +been made at build time, not at run time as in the case of the Debian +Installer. That's not to say that a live image couldn't be built to support +multiple desktops or multiple languages and offer the user a choice, but +that is not live-build's default behaviour. + +Because there is no provision made automatically for language tasks, which +include such things as language-specific fonts and input-method packages, if +you want them, you need to specify them in your configuration. For example, +a GNOME desktop image containing support for German might include these task +metapackages: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Kernel flavour and version + +One or more kernel flavours will be included in your image by default, +depending on the architecture. You can choose different flavours via the +#{--linux-flavours}# option. Each flavour is suffixed to the default stub +#{linux-image}# to form each metapackage name which in turn depends on an +exact kernel package to be included in your image. + +Thus by default, an #{amd64}# architecture image will include the +#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture +image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured +archives, you can specify a different kernel package name stub with the +#{--linux-packages}# option. For example, supposing you are building an +#{amd64}# architecture image and add the experimental archive for testing +purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# +kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Custom kernels + +You can build and include your own custom kernels, so long as they are +integrated within the Debian package management system. The live-build +system does not support kernels not built as #{.deb}# packages. + +The proper and recommended way to deploy your own kernel packages is to +follow the instructions in the #{kernel-handbook}#. Remember to modify the +ABI and flavour suffixes appropriately, then include a complete build of the +#{linux}# and matching #{linux-latest}# packages in your repository. + +If you opt to build the kernel packages without the matching metapackages, +you need to specify an appropriate #{--linux-packages}# stub as discussed in +{Kernel flavour and version}#kernel-flavour-and-version. As we explain in +{Installing modified or third-party +packages}#installing-modified-or-third-party-packages, it is best if you +include your custom kernel packages in your own repository, though the +alternatives discussed in that section work as well. + +It is beyond the scope of this document to give advice on how to customize +your kernel. However, you must at least ensure your configuration satisfies +these minimum requirements: + +_* Use an initial ramdisk. + +_* Include the union filesystem module (i.e. usually #{aufs}#). + +_* Include any other filesystem modules required by your configuration +(i.e. usually #{squashfs}#). + +2~installing-modified-or-third-party-packages Installing modified or +third-party packages + +While it is against the philosophy of a live system, it may sometimes be +necessary to build a live system with modified versions of packages that are +in the Debian repository. This may be to modify or support additional +features, languages and branding, or even to remove elements of existing +packages that are undesirable. Similarly, "third-party" packages may be used +to add bespoke and/or proprietary functionality. + +This section does not cover advice regarding building or maintaining +modified packages. Joachim Breitner's 'How to fork privately' method from +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +may be of interest, however. The creation of bespoke packages is covered in +the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ +and elsewhere. + +There are two ways of installing modified custom packages: + +_* #{packages.chroot}# + +_* Using a custom APT repository + +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" +customizations but has a number of drawbacks, while using a custom APT +repository is more time-consuming to set up. + +3~ Using #{packages.chroot}# to install custom packages + +To install a custom package, simply copy it to the +#{config/packages.chroot/}# directory. Packages that are inside this +directory will be automatically installed into the live system during build +- you do not need to specify them elsewhere. + +Packages *{must}* be named in the prescribed way. One simple way to do this +is to use #{dpkg-name}#. + +Using #{packages.chroot}# for installation of custom packages has +disadvantages: + +_* It is not possible to use secure APT. + +_* You must install all appropriate packages in the +#{config/packages.chroot/}# directory. + +_* It does not lend itself to storing live system configurations in revision +control. + +3~ Using an APT repository to install custom packages + +Unlike using #{packages.chroot}#, when using a custom APT repository you +must ensure that you specify the packages elsewhere. See {Choosing packages +to install}#choosing-packages-to-install for details. + +While it may seem unnecessary effort to create an APT repository to install +custom packages, the infrastructure can be easily re-used at a later date to +offer updates of the modified packages. + +3~ Custom packages and APT + +live-build uses APT to install all packages into the live system so will +therefore inherit behaviours from this program. One relevant example is that +(assuming a default configuration) given a package available in two +different repositories with different version numbers, APT will elect to +install the package with the higher version number. + +Because of this, you may wish to increment the version number in your custom +packages' #{debian/changelog}# files to ensure that your modified version is +installed over one in the official Debian repositories. This may also be +achieved by altering the live system's APT pinning preferences - see {APT +pinning}#apt-pinning for more information. + +2~ Configuring APT at build time + +You can configure APT through a number of options applied only at build +time. (APT configuration used in the running live system may be configured +in the normal way for live system contents, that is, by including the +appropriate configurations through #{config/includes.chroot/}#.) For a +complete list, look for options starting with #{apt}# in the #{lb_config}# +man page. + +3~choosing-apt-or-aptitude Choosing apt or aptitude + +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages +at build time. Which utility is used is governed by the #{--apt}# argument +to #{lb config}#. Choose the method implementing the preferred behaviour for +package installation, the notable difference being how missing packages are +handled. + +_* #{apt}#: With this method, if a missing package is specified, the package +installation will fail. This is the default setting. + +_* #{aptitude}#: With this method, if a missing package is specified, the +package installation will succeed. + +3~ Using a proxy with APT + +One commonly required APT configuration is to deal with building an image +behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# +or #{--apt-http-proxy}# options as needed, e.g. + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Tweaking APT to save space + +You may find yourself needing to save some space on the image medium, in +which case one or the other or both of the following options may be of +interest. + +If you don't want to include APT indices in the image, you can omit those +with: + +code{ + + $ lb config --apt-indices false + +}code + +This will not influence the entries in #{/etc/apt/sources.list}#, but merely +whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is +that APT needs those indices in order to operate in the live system, so +before performing #{apt-cache search}# or #{apt-get install}#, for instance, +the user must #{apt-get update}# first to create those indices. + +If you find the installation of recommended packages bloats your image too +much, provided you are prepared to deal with the consequences discussed +below, you may disable that default option of APT with: + +code{ + + $ lb config --apt-recommends false + +}code + +The most important consequence of turning off recommends is that +#{live-boot}# and #{live-config}# themselves recommend some packages that +provide important functionality used by most Live configurations, such as +#{user-setup}# which #{live-config}# recommends and is used to create the +live user. In all but the most exceptional circumstances you need to add +back at least some of these recommends to your package lists or else your +image will not work as expected, if at all. Look at the recommended packages +for each of the #{live-*}# packages included in your build and if you are +not certain you can omit them, add them back into your package lists. + +The more general consequence is that if you don't install recommended +packages for any given package, that is, "packages that would be found +together with this one in all but unusual installations" (Debian Policy +Manual, section 7.2), some packages that users of your Live system actually +need may be omitted. Therefore, we suggest you review the difference turning +off recommends makes to your packages list (see the #{binary.packages}# file +generated by #{lb build}#) and re-include in your list any missing packages +that you still want installed. Alternatively, if you find you only want a +small number of recommended packages left out, leave recommends enabled and +set a negative APT pin priority on selected packages to prevent them from +being installed, as explained in {APT pinning}#apt-pinning. + +3~ Passing options to apt or aptitude + +If there is not a #{lb config}# option to alter APT's behaviour in the way +you need, use #{--apt-options}# or #{--aptitude-options}# to pass any +options through to your configured APT tool. See the man pages for #{apt}# +and #{aptitude}# for details. Note that both options have default values +that you will need to retain in addition to any overrides you may +provide. So, for example, suppose you have included something from +#{snapshot.debian.org}# for testing purposes and want to specify +#{Acquire::Check-Valid-Until=false}# to make APT happy with the stale +#{Release}# file, you would do so as per the following example, appending +the new option after the default value #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Please check the man pages to fully understand these options and when to use +them. This is an example only and should not be construed as advice to +configure your image this way. This option would not be appropriate for, +say, a final release of a live image. + +For more complicated APT configurations involving #{apt.conf}# options you +might want to create a #{config/apt/apt.conf}# file instead. See also the +other #{apt-*}# options for a few convenient shortcuts for frequently needed +options. + +3~apt-pinning APT pinning + +For background, please first read the #{apt_preferences(5)}# man page. APT +pinning can be configured either for build time, or else for run time. For +the former, create #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the +latter, create #{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live +packages that end up in the binary image to be installed from sid at build +time. You need to add sid to your APT sources and pin the live packages from +it higher, but all other packages from it lower, than the default +priority. Thus, only the packages you want are installed from sid at build +time and all others are taken from the target system distribution, +${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Negative pin priorities will prevent a package from being installed, as in +the case where you do not want a package that is recommended by another +package. Suppose you are building an LXDE image using #{task-lxde-desktop}# +in #{config/package-lists/desktop.list.chroot}#, but don't want the user +prompted to store wifi passwords in the keyring. This metapackage depends on +/{lxde-core}/, which recommends /{gksu}/, which in turn recommends +/{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ +package. This can be done by adding the following stanza to +#{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-runtime.ssi new file mode 100644 index 0000000..3e44cb3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_customization-runtime.ssi @@ -0,0 +1,441 @@ +:B~ Customizing run time behaviours + +1~customizing-run-time-behaviours Customizing run time behaviours + +All configuration that is done during run time is done by live-config. Here +are some of the most common options of live-config that users are interested +in. A full list of all possibilities can be found in the man page of +live-config. + +2~ Customizing the live user + +One important consideration is that the live user is created by live-boot at +boot time, not by live-build at build time. This not only influences where +materials relating to the live user are introduced in your build, as +discussed in {Live/chroot local includes}#live-chroot-local-includes, but +also any groups and permissions associated with the live user. + +You can specify additional groups that the live user will belong to by using +any of the possibilities to configure live-config. For example, to add the +live user to the #{fuse}# group, you can either add the following file in +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +or use +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +as a boot parameter. + +It is also possible to change the default username "user" and the default +password "live". If you want to do that for any reason, you can easily +achieve it as follows: + +To change the default username you can simply specify it in your config: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +One possible way of changing the default password is by means of a hook as +described in {Boot-time hooks}#boot-time-hooks. In order to do that you can +use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, +prefix it accordingly (e.g. 2000-passwd) and add it to +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Customizing locale and language + +When the live system boots, language is involved in two steps: + +_* the locale generation + +_* setting the keyboard configuration + +The default locale when building a Live system is +#{locales=en_US.UTF-8}#. To define the locale that should be generated, use +the #{locales}# parameter in the #{--bootappend-live}# option of #{lb +config}#, e.g. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Multiple locales may be specified as a comma-delimited list. + +This parameter, as well as the keyboard configuration parameters indicated +below, can also be used at the kernel command line. You can specify a locale +by #{language_country}# (in which case the default encoding is used) or the +full #{language_country.encoding}# word. A list of supported locales and the +encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. + +Both the console and X keyboard configuration are performed by +#{live-config}# using the #{console-setup}# package. To configure them, use +the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and +#{keyboard-model}# boot parameters via the #{--bootappend-live}# +option. Valid options for these can be found in +#{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a +given language, try searching for the English name of the language and/or +the country where the language is spoken, e.g: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Note that each variant lists the layout to which it applies in the +description. + +Often, only the layout needs to be configured. For example, to get the +locale files for German and Swiss German keyboard layout in X use: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +However, for very specific use cases, you may wish to include other +parameters. For example, to set up a French system with a French-Dvorak +layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Multiple values may be specified as comma-delimited lists for each of the +#{keyboard-*}# options, with the exception of #{keyboard-model}#, which +accepts only one value. Please see the #{keyboard(5)}# man page for details +and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and +#{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are +given, they will be matched one-to-one with #{keyboard-layouts}# values (see +#{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to +define two layouts, the default being US QWERTY and the other being US +Dvorak, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistence + +A live cd paradigm is a pre-installed system which runs from read-only +media, like a cdrom, where writes and modifications do not survive reboots +of the host hardware which runs it. + +A live system is a generalization of this paradigm and thus supports other +media in addition to CDs; but still, in its default behaviour, it should be +considered read-only and all the run-time evolutions of the system are lost +at shutdown. + +'Persistence' is a common name for different kinds of solutions for saving +across reboots some, or all, of this run-time evolution of the system. To +understand how it works it would be handy to know that even if the system is +booted and run from read-only media, modifications to the files and +directories are written on writable media, typically a ram disk (tmpfs) and +ram disks' data do not survive reboots. + +The data stored on this ramdisk should be saved on a writable persistent +medium like local storage media, a network share or even a session of a +multisession (re)writable CD/DVD. All these media are supported in live +systems in different ways, and all but the last one require a special boot +parameter to be specified at boot time: #{persistence}#. + +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not +set), local storage media (e.g. hard disks, USB drives) will be probed for +persistence volumes during boot. It is possible to restrict which types of +persistence volumes to use by specifying certain boot parameters described +in the live-boot(7) man page. A persistence volume is any of the following: + +_* a partition, identified by its GPT name. + +_* a filesystem, identified by its filesystem label. + +_* an image file located on the root of any readable filesystem (even an +NTFS partition of a foreign OS), identified by its filename. + +The volume label for overlays must be #{persistence}# but it will be ignored +unless it contains in its root a file named #{persistence.conf}# which is +used to fully customize the volume's persistence, this is to say, specifying +the directories that you want to save in your persistence volume after a +reboot. See {The persistence.conf file}#persistence-conf for more details. + +Here are some examples of how to prepare a volume to be used for +persistence. It can be, for instance, an ext4 partition on a hard disk or on +a usb key created with, e.g.: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +See also {Using the space left on a USB stick}#using-usb-extra-space. + +If you already have a partition on your device, you could just change the +label with one of the following: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Here's an example of how to create an ext4-based image file to be used for +persistence: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Once the image file is created, as an example, to make #{/usr}# persistent +but only saving the changes you make to that directory and not all the +contents of #{/usr}#, you can use the "union" option. If the image file is +located in your home directory, copy it to the root of your hard drive's +filesystem and mount it in #{/mnt}# as follows: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Then, create the #{persistence.conf}# file adding content and unmount the +image file. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Now, reboot into your live medium with the boot parameter "persistence". + +3~persistence-conf The persistence.conf file + +A volume with the label #{persistence}# must be configured by means of the +#{persistence.conf}# file to make arbitrary directories persistent. That +file, located on the volume's filesystem root, controls which directories it +makes persistent, and in which way. + +How custom overlay mounts are configured is described in full detail in the +persistence.conf(5) man page, but a simple example should be sufficient for +most uses. Let's say we want to make our home directory and APT cache +persistent in an ext4 filesystem on the /dev/sdb1 partition: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Then we reboot. During the first boot the contents of #{/home}# and +#{/var/cache/apt}# will be copied into the persistence volume, and from then +on all changes to these directories will live in the persistence +volume. Please note that any paths listed in the #{persistence.conf}# file +cannot contain white spaces or the special #{.}# and #{..}# path +components. Also, neither #{/lib}#, #{/lib/live}# (or any of their +sub-directories) nor #{/}# can be made persistent using custom mounts. As a +workaround for this limitation you can add #{/ union}# to your +#{persistence.conf}# file to achieve full persistence. + +3~ Using more than one persistence store + +There are different methods of using multiple persistence store for +different use cases. For instance, using several volumes at the same time or +selecting only one, among various, for very specific purposes. + +Several different custom overlay volumes (with their own +#{persistence.conf}# files) can be used at the same time, but if several +volumes make the same directory persistent, only one of them will be +used. If any two mounts are "nested" (i.e. one is a sub-directory of the +other) the parent will be mounted before the child so no mount will be +hidden by the other. Nested custom mounts are problematic if they are listed +in the same #{persistence.conf}# file. See the persistence.conf(5) man page +for how to handle that case if you really need it (hint: you usually don't). + +One possible use case: If you wish to store the user data i.e. #{/home}# and +the superuser data i.e. #{/root}# in different partitions, create two +partitions with the #{persistence}# label and add a #{persistence.conf}# +file in each one like this, #{# echo "/home" > persistence.conf}# for the +first partition that will save the user's files and #{# echo "/root" > +persistence.conf}# for the second partition which will store the superuser's +files. Finally, use the #{persistence}# boot parameter. + +If a user would need multiple persistence store of the same type for +different locations or testing, such as #{private}# and #{work}#, the boot +parameter #{persistence-label}# used in conjunction with the boot parameter +#{persistence}# will allow for multiple but unique persistence media. An +example would be if a user wanted to use a persistence partition labeled +#{private}# for personal data like browser bookmarks or other types, they +would use the boot parameters: #{persistence}# +#{persistence-label=private}#. And to store work related data, like +documents, research projects or other types, they would use the boot +parameters: #{persistence}# #{persistence-label=work}#. + +It is important to remember that each of these volumes, #{private}# and +#{work}#, also needs a #{persistence.conf}# file in its root. The live-boot +man page contains more information about how to use these labels with legacy +names. + +3~ Using persistence with encryption + +Using the persistence feature means that some sensible data might get +exposed to risk. Especially if the persistent data is stored on a portable +device such as a usb stick or an external hard drive. That is when +encryption comes in handy. Even if the entire procedure might seem +complicated because of the number of steps to be taken, it is really easy to +handle encrypted partitions with live-boot. In order to use *{luks}*, which +is the supported encryption type, you need to install /{cryptsetup}/ both on +the machine you are creating the encrypted partition with and also in the +live system you are going to use the encrypted persistent partition with. + +To install /{cryptsetup}/ on your machine: + +code{ + + # apt-get install cryptsetup + +}code + +To install /{cryptsetup}/ in your live system, add it to your package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Once you have your live system with /{cryptsetup}/, you basically only need +to create a new partition, encrypt it and boot with the #{persistence}# and +#{persistence-encryption=luks}# parameters. We could have already +anticipated this step and added the boot parameters following the usual +procedure: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Let's go into the details for all of those who are not familiar with +encryption. In the following example we are going to use a partition on a +usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need +to determine which partition is the one you are going to use in your +specific case. + +The first step is plugging in your usb stick and determine which device it +is. The recommended method of listing devices in live-manual is using #{ls +-l /dev/disk/by-id}#. After that, create a new partition and then, encrypt +it with a passphrase as follows: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Then open the luks partition in the virtual device mapper. Use any name you +like. We use *{live}* here as an example: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +The next step is filling the device with zeros before creating the +filesystem: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Now, we are ready to create the filesystem. Notice that we are adding the +label #{persistence}# so that the device is mounted as persistence store at +boot time. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +To continue with our setup, we need to mount the device, for example in +#{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +And create the #{persistence.conf}# file in the root of the partition. This +is, as explained before, strictly necessary. See {The persistence.conf +file}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Then unmount the mount point: + +code{ + + # umount /mnt + +}code + +And optionally, although it might be a good way of securing the data we have +just added to the partition, we can close the device: + +code{ + + # cryptsetup luksClose live + +}code + +Let's summarize the process. So far, we have created an encryption capable +live system, which can be copied to a usb stick as explained in {Copying an +ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also +created an encrypted partition, which can be located in the same usb stick +to carry it around and we have configured the encrypted partition to be used +as persistence store. So now, we only need to boot the live system. At boot +time, live-boot will prompt us for the passphrase and will mount the +encrypted partition to be used for persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_installation.ssi new file mode 100644 index 0000000..3841f4c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_installation.ssi @@ -0,0 +1,173 @@ +:B~ Installation + +1~installation Installation + +2~requirements Requirements + +Building live system images has very few system requirements: + +_* Superuser (root) access + +_* An up-to-date version of live-build + +_* A POSIX-compliant shell, such as /{bash}/ or /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6 or newer. + +Note that using Debian or a Debian-derived distribution is not required - +live-build will run on almost any distribution with the above requirements. + +2~installing-live-build Installing live-build + +You can install live-build in a number of different ways: + +_* From the Debian repository + +_* From source + +_* From snapshots + +If you are using Debian, the recommended way is to install live-build via +the Debian repository. + +3~ From the Debian repository + +Simply install live-build like any other package: + +code{ + + # apt-get install live-build + +}code + +3~ From source + +live-build is developed using the Git version control system. On Debian +based systems, this is provided by the /{git}/ package. To check out the +latest code, execute: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +You can build and install your own Debian package by executing: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Now install whichever of the freshly built #{.deb}# files you were +interested in, e.g. + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +You can also install live-build directly to your system by executing: + +code{ + + # make install + +}code + +and uninstall it with: + +code{ + + # make uninstall + +}code + +3~ From 'snapshots' + +If you do not wish to build or install live-build from source, you can use +snapshots. These are built automatically from the latest version in Git and +are available on http://live-systems.org/debian/. + +2~ Installing live-boot and live-config + +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. + +3~ From the Debian repository + +Both live-boot and live-config are available from the Debian repository as +per {Installing live-build}#installing-live-build. + +3~ From source + +To use the latest source from git, you can follow the process below. Please +ensure you are familiar with the terms mentioned in {Terms}#terms. + +_* Checkout the live-boot and live-config sources + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consult the live-boot and live-config man pages for details on customizing +if that is your reason for building these packages from source. + +_* Build live-boot and live-config .deb files + +You must build either on your target distribution or in a chroot containing +your target platform: this means if your target is ${testing} then you +should build against ${testing}. + +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to +build live-boot for a target distribution that differs from your build +system. For example, for ${testing} live images, build live-boot in a +${testing} chroot. If your target distribution happens to match your build +system distribution, you may build directly on the build system using +#{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Use applicable generated .deb files + +As live-boot and live-config are installed by live-build system, installing +the packages in the host system is not sufficient: you should treat the +generated .deb files like any other custom packages. Since your purpose for +building from source is likely to test new things over the short term before +the official release, follow {Installing modified or third-party +packages}#installing-modified-or-third-party-packages to temporarily include +the relevant files in your configuration. In particular, notice that both +packages are divided into a generic part, a documentation part and one or +more back-ends. Include the generic part, only one back-end matching your +configuration, and optionally the documentation. Assuming you are building a +live image in the current directory and have generated all .deb files for a +single version of both packages in the directory above, these bash commands +would copy all of the relevant packages including default back-ends: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ From 'snapshots' + +You can let live-build automatically use the latest snapshots of live-boot +and live-config by configuring the package repository on live-systems.org as +a third-party repository in your live-build configuration directory. diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_managing_a_configuration.ssi new file mode 100644 index 0000000..6d54371 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_managing_a_configuration.ssi @@ -0,0 +1,133 @@ +:B~ Managing a configuration + +1~managing-a-configuration Managing a configuration + +This chapter explains how to manage a live configuration from initial +creation, through successive revisions and successive releases of both the +live-build software and the live image itself. + +2~ Dealing with configuration changes + +Live configurations rarely are perfect on the first try. It may be fine to +pass #{lb config}# options from the command-line to perform a single build, +but it is more typical to revise those options and build again until you are +satisfied. To support these changes, you will need auto scripts which ensure +your configuration is kept in a consistent state. + +3~ Why use auto scripts? What do they do? + +The #{lb config}# command stores the options you pass to it in #{config/*}# +files along with many other options set to default values. If you run #{lb +config}# again, it will not reset any option that was defaulted based on +your initial options. So, for example, if you run #{lb config}# again with a +new value for #{--binary-images}#, any dependent options that were defaulted +for the old image type may no longer work with the new ones. Nor are these +files intended to be read or edited. They store values for over a hundred +options, so nobody, let alone yourself, will be able to see in these which +options you actually specified. And finally, if you run #{lb config}#, then +upgrade live-build and it happens to rename an option, #{config/*}# would +still contain variables named after the old option that are no longer valid. + +For all these reasons, #{auto/*}# scripts will make your life easier. They +are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# +commands that are designed to help you manage your configuration. The +#{auto/config}# script stores your #{lb config}# command with all desired +options, the #{auto/clean}# script removes the files containing +configuration variable values, and the #{auto/build}# script keeps a +#{build.log}# of each build. Each of these scripts is run automatically +every time you run the corresponding #{lb}# command. By using these scripts, +your configuration is easier to read and is kept internally consistent from +one revision to the next. Also, it will be much easier for you identify and +fix options which need to change when you upgrade live-build after reading +the updated documentation. + +3~ Use example auto scripts + +For your convenience, live-build comes with example auto shell scripts to +copy and edit. Start a new, default configuration, then copy the examples +into it: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Edit #{auto/config}#, adding any options as you see fit. For instance: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Now, each time you use #{lb config}#, #{auto/config}# will reset the +configuration based on these options. When you want to make changes to them, +edit the options in this file instead of passing them to #{lb config}#. When +you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files +along with any other build products. And finally, when you use #{lb build}#, +a log of the build will be written by #{auto/build}# in #{build.log}#. + +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. + +2~clone-configuration-via-git Clone a configuration published via Git + +Use the #{lb config --config}# option to clone a Git repository that +contains a live system configuration. If you would like to base your +configuration on one maintained by the ${project}, look at +http://live-systems.org/gitweb/ for the repository named #{live-images}# in +the category #{Packages}#. This repository contains the configurations for +the live systems {prebuilt images}#downloading-prebuilt-images. + +For example, to build a standard image, use the #{live-images}# repository +as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Edit #{auto/config}# and any other things you need in the #{config}# tree to +suit your needs. For example, the unofficial non-free prebuilt images are +made by simply adding #{--archive-areas "main contrib non-free"}#. + +You may optionally define a shortcut in your Git configuration by adding the +following to your #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +This enables you to use #{lso:}# anywhere you need to specify the address of +a #{live-systems.org}# git repository. If you also drop the optional +#{.git}# suffix, starting a new image using this configuration is as easy +as: + +code{ + + $ lb config --config lso:live-images + +}code + +Cloning the entire #{live-images}# repository pulls the configurations used +for several images. If you feel like building a different image after you +have finished with the first one, change to another directory and again and +optionally, make any changes to suit your needs. + +In any case, remember that every time you will have to build the image as +superuser: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/de/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/de/user_overview.ssi new file mode 100644 index 0000000..073a266 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/de/user_overview.ssi @@ -0,0 +1,130 @@ +:B~ Overview of tools + +1~overview-of-tools Overview of tools + +This chapter contains an overview of the three main tools used in building +live systems: live-build, live-boot and live-config. + +2~live-build The live-build package + +live-build is a collection of scripts to build live systems. These scripts +are also referred to as "commands". + +The idea behind live-build is to be a framework that uses a configuration +directory to completely automate and customize all aspects of building a +Live image. + +Many concepts are similar to those used to build Debian packages with +/{debhelper}/: + +_* The scripts have a central location for configuring their operation. In +/{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For +example, dh_install will look, among others, for a file called +#{debian/install}# to determine which files should exist in a particular +binary package. In much the same way, live-build stores its configuration +entirely under a #{config/}# subdirectory. + +_* The scripts are independent - that is to say, it is always safe to run +each command. + +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton +configuration directory. This could be considered to be similar to tools +such as /{dh-make}/. For more information about these tools, read on, since +the remainder of this section discuses the four most important +commands. Note that the preceding #{lb}# is a generic wrapper for live-build +commands. + +_* *{lb config}*: Responsible for initializing a Live system configuration +directory. See {The lb config command}#lb-config for more information. + +_* *{lb build}*: Responsible for starting a Live system build. See {The lb +build command}#lb-build for more information. + +_* *{lb clean}*: Responsible for removing parts of a Live system build. See +{The lb clean command}#lb-clean for more information. + +3~lb-config The #{lb config}# command + +As discussed in {live-build}#live-build, the scripts that make up live-build +read their configuration with the #{source}# command from a single directory +named #{config/}#. As constructing this directory by hand would be +time-consuming and error-prone, the #{lb config}# command can be used to +create the initial skeleton configuration tree. + +Issuing #{lb config}# without any arguments creates the #{config/}# +subdirectory which is populated with some default settings in configuration +files, and two skeleton trees named #{auto/}# and #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Using #{lb config}# without any arguments would be suitable for users who +need a very basic image, or who intend to provide a more complete +configuration via #{auto/config}# later (see {Managing a +configuration}#managing-a-configuration for details). + +Normally, you will want to specify some options. For example, to specify +which package manager to use while building the image: + +code{ + + $ lb config --apt aptitude + +}code + +It is possible to specify many options, such as: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +A full list of options is available in the #{lb_config}# man page. + +3~lb-build The #{lb build}# command + +The #{lb build}# command reads in your configuration from the #{config/}# +directory. It then runs the lower level commands needed to build your Live +system. + +3~lb-clean The #{lb clean}# command + +It is the job of the #{lb clean}# command to remove various parts of a build +so subsequent builds can start from a clean state. By default, #{chroot}#, +#{binary}# and #{source}# stages are cleaned, but the cache is left +intact. Also, individual stages can be cleaned. For example, if you have +made changes that only affect the binary stage, use #{lb clean --binary}# +prior to building a new binary. If your changes invalidate the bootstrap +and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or +#{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man +page for a full list of options. + +2~live-boot The live-boot package + +live-boot is a collection of scripts providing hooks for the +/{initramfs-tools}/, used to generate an initramfs capable of booting live +systems, such as those created by live-build. This includes the live system +ISOs, netboot tarballs, and USB stick images. + +At boot time it will look for read-only media containing a #{/live/}# +directory where a root filesystem (often a compressed filesystem image like +squashfs) is stored. If found, it will create a writable environment, using +aufs, for Debian like systems to boot from. + +More information on initial ramfs in Debian can be found in the Debian Linux +Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter +on initramfs. + +2~live-config The live-config package + +live-config consists of the scripts that run at boot time after live-boot to +configure the live system automatically. It handles such tasks as setting +the hostname, locales and timezone, creating the live user, inhibiting cron +jobs and performing autologin of the live user. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/en/about_manual.ssi new file mode 100644 index 0000000..b91494b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/about_manual.ssi @@ -0,0 +1,161 @@ +:B~ About this manual + +1~about-manual About this manual + +This manual serves as a single access point to all documentation related to the ${project} and in particular applies to the software produced by the project for the Debian 9.0 "${stable}" release. An up-to-date version can always be found at http://live-systems.org/ + +While live-manual is primarily focused on helping you build a live system and not on end-user topics, an end user may find some useful information in these sections: {The Basics}#the-basics covers downloading prebuilt images and preparing images to be booted from media or the network, either using the web builder or running live-build directly on your system. {Customizing run time behaviours}#customizing-run-time-behaviours describes some options that may be specified at the boot prompt, such as selecting a keyboard layout and locale, and using persistence. + +Some of the commands mentioned in the text must be executed with superuser privileges which can be obtained by becoming the root user via #{su}# or by using #{sudo}#. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by #{$}# or #{#}# respectively. This symbol is not a part of the command. + +2~ For the impatient + +While we believe that everything in this manual is important to at least some of our users, we realize it is a lot of material to cover and that you may wish to experience early success using the software before delving into the details. Therefore, we suggest reading in the following order. + +First, read this chapter, {About this manual}#about-manual, from the beginning and ending with the {Terms}#terms section. Next, skip to the three tutorials at the front of the {Examples}#examples section designed to teach you image building and customization basics. Read {Using the examples}#using-the-examples first, followed by {Tutorial 1: A default image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these tutorials, you will have a taste of what can be done with live systems. + +We encourage you to return to more in-depth study of the manual, perhaps next reading {The basics}#the-basics, skimming or skipping {Building a netboot image}#building-netboot-image, and finishing by reading the {Customization overview}#customization-overview and the chapters that follow it. By this point, we hope you are thoroughly excited by what can be done with live systems and motivated to read the rest of the manual, cover-to-cover. + +2~terms Terms + +_* *{Live system}*: An operating system that can boot without installation to a hard drive. Live systems do not alter local operating system(s) or file(s) already installed on the computer hard drive unless instructed to do so. Live systems are typically booted from media such as CDs, DVDs or USB sticks. Some may also boot over the network (via netboot images, see {Building a netboot image}#building-netboot-image), and over the Internet (via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). + +_* *{Live medium}*: As distinct from live system, the live medium refers to the CD, DVD or USB stick where the binary produced by live-build and used to boot the live system is written. More broadly, the term also refers to any place where this binary resides for the purposes of booting the live system, such as the location for the network boot files. + +_* *{${project}}*: The project which maintains, among others, the live-boot, live-build, live-config, live-tools and live-manual packages. + +_* *{Host system}*: The environment used to create the live system. + +_* *{Target system}*: The environment used to run the live system. + +_* *{live-boot}*: A collection of scripts used to boot live systems. + +_* *{live-build}*: A collection of scripts used to build customized live systems. + +_* *{live-config}*: A collection of scripts used to configure a live system during the boot process. + +_* *{live-tools}*: A collection of additional scripts used to perform useful tasks within a running live system. + +_* *{live-manual}*: This document is maintained in a package called live-manual. + +_* *{Debian Installer (d-i)}*: The official installation system for the Debian distribution. + +_* *{Boot parameters}*: Parameters that can be entered at the bootloader prompt to influence the kernel or live-config. + +_* *{chroot}*: The /{chroot}/ program, #{chroot(8)}#, enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting. + +_* *{Binary image}*: A file containing the live system, such as live-image-i386.hybrid.iso or live-image-i386.img. + +_* *{Target distribution}*: The distribution upon which your live system will be based. This can differ from the distribution of your host system. + +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently codenamed ${stable}, contains the latest officially released distribution of Debian. The *{testing}* distribution, temporarily codenamed ${testing}, is the staging area for the next *{stable}* release. A major advantage of using this distribution is that it has more recent versions of software relative to the *{stable}* release. The *{unstable}* distribution, permanently codenamed sid, is where active development of Debian occurs. Generally, this distribution is run by developers and those who like to live on the edge. Throughout the manual, we tend to use codenames for the releases, such as ${testing} or sid, as that is what is supported by the tools themselves. + +2~ Authors + +A list of authors (in alphabetical order): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contributing to this document + +This manual is intended as a community project and all proposals for improvements and contributions are extremely welcome. Please see the section {Contributing to the project}#contributing-to-project for detailed information on how to fetch the commit key and make good commits. + +3~applying-changes Applying changes + +In order to make changes to the English manual you have to edit the right files in #{manual/en/}# but prior to the submission of your contribution, please preview your work. To preview the live-manual, ensure the packages needed for building it are installed by executing: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +You may build the live-manual from the top level directory of your Git checkout by executing: + +code{ + + $ make build + +}code + +Since it takes a while to build the manual in all supported languages, authors may find it convenient to use one of the fast proofing shortcuts when reviewing the new documentation they have added to the English manual. Using #{PROOF=1}# builds live-manual in html format, but without the segmented html files, and using #{PROOF=2}# builds live-manual in pdf format, but only the A4 and letter portraits. That is why using either of the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: + +code{ + + $ make build PROOF=1 + +}code + +When proofing one of the translations it is possible to build only one language by executing, e.g: + +code{ + + $ make build LANGUAGES=de + +}code + +It is also possible to build by document type, e.g: + +code{ + + $ make build FORMATS=pdf + +}code + +Or combine both, e.g: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +After revising your work and making sure that everything is fine, do not use #{make commit}# unless you are updating translations in the commit, and in that case, do not mix changes to the English manual and translations in the same commit, but use separate commits for each. See the {Translation}#translation section for more details. + +3~translation Translation + +In order to translate live-manual, follow these steps depending on whether you are starting a translation from scratch or continue working on an already existing one: + +_* Start a new translation from scratch + +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and *{index.html.in.pot}* files in #{manual/pot/}# to your language with your favourite editor (such as /{poedit}/) and send the translated #{.po}# files to the mailing list to check their integrity. live-manual's integrity check not only ensures that the #{.po}# files are 100% translated but it also detects possible errors. + +_2* Once checked, to enable a new language in the autobuild it is enough to add the initial translated files to #{manual/po/${LANGUAGE}/}# and run #{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the name of the language and its name in English between brackets. + +_* Continue with an already started translation + +_2* If your target language has already been added, you can randomly continue translating the remaining .po files in #{manual/po/${LANGUAGE}/}# using your favourite editor (such as /{poedit}/). + +_2* Do not forget that you need to run #{make commit}# to ensure that the translated manuals are updated from the .po files and then you can review your changes launching #{make build}# before #{git add .}#, #{git commit -m "Translating..."}# and #{git push}#. Remember that since #{make build}# can take a considerable amount of time, you can proofread languages individually as explained in {Applying changes}#applying-changes + +After running #{make commit}# you will see some text scroll by. These are basically informative messages about the processing status and also some hints about what can be done in order to improve live-manual. Unless you see a fatal error, you usually can proceed and submit your contribution. + +live-manual comes with two utilities that can greatly help translators to find untranslated and changed strings. The first one is "make translate". It launches an script that tells you in detail how many untranslated strings there are in each .po file. The second one, the "make fixfuzzy" target, only acts upon changed strings but it helps you to find and fix them one by one. + +Keep in mind that even though these utilities might be really helpful to do translation work on the command line, the use of an specialized tool like /{poedit}/ is the recommended way to do the task. It is also a good idea to read the Debian localization (l10n) documentation and, specifically to live-manual, the {Guidelines for translators}#guidelines-translators. + +*{Note:}* You can use #{make clean}# to clean your git tree before pushing. This step is not compulsory thanks to the .gitignore file but it is a good practice to avoid committing files involuntarily. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/en/about_project.ssi new file mode 100644 index 0000000..442a042 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/about_project.ssi @@ -0,0 +1,67 @@ +:B~ About the ${project} + +1~about-project About the ${project} + +2~ Motivation + +3~ What is wrong with current live systems + +When ${project} was initiated, there were already several Debian based live systems available and they are doing a great job. From the Debian perspective most of them have one or more of the following disadvantages: + +_* They are not Debian projects and therefore lack support from within Debian. + +_* They mix different distributions, e.g. *{testing}* and *{unstable}*. + +_* They support i386 only. + +_* They modify the behaviour and/or appearance of packages by stripping them down to save space. + +_* They include packages from outside of the Debian archive. + +_* They ship custom kernels with additional patches that are not part of Debian. + +_* They are large and slow due to their sheer size and thus not suitable for rescue issues. + +_* They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images. + +3~ Why create our own live system? + +Debian is the Universal Operating System: Debian has a live system to show around and to accurately represent the Debian system with the following main advantages: + +_* It is a subproject of Debian. + +_* It reflects the (current) state of one distribution. + +_* It runs on as many architectures as possible. + +_* It consists of unchanged Debian packages only. + +_* It does not contain any packages that are not in the Debian archive. + +_* It uses an unaltered Debian kernel with no additional patches. + +2~ Philosophy + +3~ Only unchanged packages from Debian "main" + +We will only use packages from the Debian repository in the "main" section. The non-free section is not part of Debian and therefore cannot be used for official live system images. + +We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian. + +As an exception, our own packages such as live-boot, live-build or live-config may temporarily be used from our own repository for development reasons (e.g. to create development snapshots). They will be uploaded to Debian on a regular basis. + +3~ No package configuration of the live system + +In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian. + +Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian. + +A system for configuring packages is provided using debconf allowing custom configured packages to be installed in your custom produced live system images, but for the {prebuilt live images}#downloading-prebuilt-images we choose to leave packages in their default configuration, unless absolutely necessary in order to work in the live environment. Wherever possible, we prefer to adapt packages within the Debian archive to work better in a live system versus making changes to the live toolchain or {prebuilt image configurations}#clone-configuration-via-git. For more information, please see {Customization overview}#customization-overview. + +2~contact Contact + +_* *{Mailing list}*: The primary contact for the project is the mailing list at https://lists.debian.org/debian-live/. You can email the list directly by addressing your mail to debian-live@lists.debian.org. The list archives are available at https://lists.debian.org/debian-live/. + +_* *{IRC}*: A number of users and developers are present in the #debian-live channel on irc.debian.org (OFTC). When asking a question on IRC, please be patient for an answer. If no answer is forthcoming, please email the mailing list. + +_* *{BTS}*: The {Debian Bug Tracking System}https://www.debian.org/Bugs/ (BTS) contains details of bugs reported by users and developers. Each bug is given a number, and is kept on file until it is marked as having been dealt with. For more information, please see {Reporting bugs}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/en/appendix_style-guide.ssi new file mode 100644 index 0000000..f64fe18 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/appendix_style-guide.ssi @@ -0,0 +1,241 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account when writing technical documentation for live-manual. They are divided into linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers of English. So as a general rule try to use short, meaningful sentences, followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a suggestion to try to avoid, as much as possible, complex subordinate sentences that make the text difficult to understand for non-native speakers of English. + +_* /{Variety of English}/ + +The most widely spread varieties of English are British and American so it is very likely that most authors will use either one or the other. In a collaborative environment, the ideal variety would be "International English" but it is very difficult, not to say impossible, to decide on which variety among all the existing ones, is the best to use. + +We expect that different varieties may mix without creating misunderstandings but in general terms you should try to be coherent and before deciding on using British, American or any other English flavour at your discretion, please take a look at how other people write and try to imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely unrelated to live-manual. Technical writing should be as neutral as possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make references to the third person singular preferably use "they" rather than "he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +Go straight to the point and do not wander around aimlessly. Give as much information as necessary but do not give more information than necessary, this is to say, do not explain unnecessary details. Your readers are intelligent. Presume some previous knowledge on their part. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several other languages. This implies that a number of people will have to do an extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +As suggested before, it is almost impossible to standardize a collaborative document into a perfectly unified whole. However, every effort on your side to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and unambiguous. (Text-forming devices are linguistic markers such as connectors). + +_* /{Be descriptive}/ + +It is preferable to describe the point in one or several paragraphs than merely using a number of sentences in a typical "changelog" style. Describe it! Your readers will appreciate it. + +_* /{Dictionary}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not know how to express certain concepts in English. But keep in mind that a dictionary can either be your best friend or can turn into your worst enemy if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million words). Many of these words are borrowings from other languages. When looking up the meaning of words in a bilingual dictionary the tendency of a non-native speaker of English is to choose the one that sounds more similar in their mother tongue. This often turns into an excessively formal discourse which does not sound quite natural in English. + +As a general rule, if a concept can be expressed using different synonyms, it is a good advice to choose the first word proposed by the dictionary. If in doubt, choosing words of Germanic origin (Usually monosyllabic words) is often the right thing to do. Be warned that these two techniques might produce a rather informal discourse but at least your choice of words will be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign language you cannot help falling from time to time in the trap of the so called "false friends", words that look similar in two languages but whose meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may convey a completely different meaning from what their individual words seem to mean. Sometimes, idioms might be difficult to understand even for native speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand and above all contractions that try to imitate the spoken language. Not to mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +It is important that authors test their examples before adding them to live-manual to ensure that everything works as described. Testing on a clean chroot or VM can be a good starting point. Besides, it would be ideal if the tests were then carried out on different machines with different hardware to spot possible problems that may arise. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, after all, just an example. + +It is often better to use a line that only applies to a specific case than using abstractions that may confuse your readers. In this case you can provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some potentially dangerous commands that, if misused, may cause data loss or other similar undesirable effects. In this case you should provide a thorough explanation of the possible side effects. + +_* /{External links}/ + +Links to external sites should only be used when the information on those sites is crucial when it comes to understanding a special point. Even so, try to use links to external sites as sparsely as possible. Internet links are likely to change from time to time resulting in broken links and leaving your arguments in an incomplete state. + +Besides, people who read the manual offline will not have the chance to follow those links. + +_* /{Avoid branding and things that violate the license under which the manual is published}/ + +Try to avoid branding as much as possible. Keep in mind that other downstream projects might make use of the documentation you write. So you are complicating things for them if you add certain specific material. + +live-manual is licensed under the GNU GPL. This has a number of implications that apply to the distribution of the material (of any kind, including copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence of events. + + - Once you have somehow organized those ideas in your mind write a first draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names of the releases, such as ${testing} or sid, should not be capitalized when referred to as code names. In order to check the spelling you can run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup below. + +If you have to enumerate a series of steps or stages in your description, you can also use ordinal numbers: First, second, third ... or First, Then, After that, Finally ... Alternatively you can use bulleted items. + +_* /{Markup}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to process the text files and produce a multiple format output. It is recommended to take a look at {SiSU's manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the translation rules that apply to their specific languages. Usually, translation groups and mailing lists provide information on how to produce translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +The role of the translator is to convey as faithfully as possible the meaning of words, sentences, paragraphs and texts as written by the original authors into their target language. + +So they should refrain from adding personal comments or extra bits of information of their own. If they want to add a comment for other translators working on the same documents, they can leave it in the space reserved for that. That is, the header of the strings in the *{po}* files preceded by a number sign *{#}*. Most graphical translation programs can automatically handle those types of comments. + +_* /{TN, Translator's Note}/ + +It is perfectly acceptable however, to include a word or an expression in brackets in the translated text if, and only if, that makes the meaning of a difficult word or expression clearer to the reader. Inside the brackets the translator should make evident that the addition was theirs using the abbreviation "TN" or "Translator's Note". + +_* /{Impersonal sentences}/ + +Documents written in English make an extensive use of the impersonal form "you". In some other languages that do not share this characteristic, this might give the false impression that the original texts are directly addressing the reader when they are actually not doing so. Translators must be aware of that fact and reflect it in their language as accurately as possible. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to translators. Double check the meaning of suspicious false friends if in doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* files will find many markup features in the strings. They can translate the text anyway, as long as it is translatable, but it is extremely important that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in the translation is the only way to score a 100% complete translation. And even though it means more work at first because it might require the intervention of the translators if the code changes, it is the best way, in the long run, to identify what has already been translated and what has not when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original texts. Be careful to press the "Enter" key or type *{\n}* if they appear in the original files. These newlines often appear, for instance, in the code blocks. + +Make no mistake, this does not mean that the translated text needs to have the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths diff --git a/markup/pod-samples/pod/live-manual/media/text/en/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/en/examples.ssi new file mode 100644 index 0000000..262d09b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/examples.ssi @@ -0,0 +1,325 @@ +:B~ Examples + +1~examples Examples + +This chapter covers example builds for specific use cases with live systems. If you are new to building your own live system images, we recommend you first look at the three tutorials in sequence, as each one teaches new techniques that will help you use and understand the remaining examples. + +2~using-the-examples Using the examples + +To use these examples you need a system to build them on that meets the requirements listed in {Requirements}#requirements and has live-build installed as described in {Installing live-build}#installing-live-build. + +Note that, for the sake of brevity, in these examples we do not specify a local mirror to use for the build. You can speed up downloads considerably if you use a local mirror. You may specify the options when you use #{lb config}#, as described in {Distribution mirrors used at build time}#distribution-mirrors-build-time, or for more convenience, set the default for your build system in #{/etc/live/build.conf}#. Simply create this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your preferred mirror. All other mirrors used in the build will be defaulted from these values. For example: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 Tutorial 1: A default image + +*{Use case:}* Create a simple first image, learning the basics of live-build. + +In this tutorial, we will build a default ISO hybrid live system image containing only base packages (no Xorg) and some live system support packages, as a first exercise in using live-build. + +You can't get much simpler than this: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examine the contents of the #{config/}# directory if you wish. You will see stored here a skeletal configuration, ready to customize or, in this case, use immediately to build a default image. + +Now, as superuser, build the image, saving a log as you build with #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Assuming all goes well, after a while, the current directory will contain #{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly in a virtual machine as described in {Testing an ISO image with Qemu}#testing-iso-with-qemu and {Testing an ISO image with VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media or a USB flash device as described in {Burning an ISO image to a physical medium}#burning-iso-image and {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb, respectively. + +2~tutorial-2 Tutorial 2: A web browser utility + +*{Use case:}* Create a web browser utility image, learning how to apply customizations. + +In this tutorial, we will create an image suitable for use as a web browser utility, serving as an introduction to customizing live system images. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Our choice of LXDE for this example reflects our desire to provide a minimal desktop environment, since the focus of the image is the single use we have in mind, the web browser. We could go even further and provide a default configuration for the web browser in #{config/includes.chroot/etc/iceweasel/profile/}#, or additional support packages for viewing various kinds of web content, but we leave this as an exercise for the reader. + +Build the image, again as superuser, keeping a log as in {Tutorial 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: A personalized image + +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. + +Since we will be changing our personalized image over a number of revisions, and we want to track those changes, trying things experimentally and possibly reverting them if things don't work out, we will keep our configuration in the popular #{git}# version control system. We will also use the best practice of autoconfiguration via #{auto}# scripts as described in {Managing a configuration}#managing-a-configuration. + +3~ First revision + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Edit #{auto/config}# to read as follows: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Perform #{lb config}# to generate the config tree, using the #{auto/config}# script you just created: + +code{ + + $ lb config + +}code + +Now populate your local package list: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +First, #{--architectures i386}# ensures that on our #{amd64}# build system, we build a 32-bit version suitable for use on most machines. Second, we use #{--linux-flavours 686-pae}# because we don't anticipate using this image on much older systems. Third, we have chosen the /{lxde}/ task metapackage to give us a minimal desktop. And finally, we have added two initial favourite packages: /{iceweasel}/ and /{xchat}/. + +Now, build the image: + +code{ + + # lb build + +}code + +Note that unlike in the first two tutorials, we no longer have to type #{2>&1 | tee build.log}# as that is now included in #{auto/build}#. + +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are satisfied it works, it's time to initialize our #{git}# repository, adding only the auto scripts we just created, and then make the first commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Second revision + +In this revision, we're going to clean up from the first build, add the /{vlc}/ package to our configuration, rebuild, test and commit. + +The #{lb clean}# command will clean up all generated files from the previous build except for the cache, which saves having to re-download packages. This ensures that the subsequent #{lb build}# will re-run all stages to regenerate the files from our new configuration. + +code{ + + # lb clean + +}code + +Now append the /{vlc}/ package to our local package list in #{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Build again: + +code{ + +# lb build + +}code + +Test, and when you're satisfied, commit the next revision: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Of course, more complicated changes to the configuration are possible, perhaps adding files in subdirectories of #{config/}#. When you commit new revisions, just take care not to hand edit or commit the top-level files in #{config}# containing #{LB_*}# variables, as these are build products, too, and are always cleaned up by #{lb clean}# and re-created with #{lb config}# via their respective #{auto}# scripts. + +We've come to the end of our tutorial series. While many more kinds of customization are possible, even just using the few features explored in these simple examples, an almost infinite variety of different images can be created. The remaining examples in this section cover several other use cases drawn from the collected experiences of users of live systems. + +2~ A VNC Kiosk Client + +*{Use case:}* Create an image with live-build to boot directly to a VNC server. + +Make a build directory and create an skeletal configuration inside it, disabling recommends to make a minimal system. And then create two initial package lists: the first one generated with a script provided by live-build named #{Packages}# (see {Generated package lists}#generated-package-lists), and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you may need to re-add some recommended packages to make your image work properly. + +An easy way to list recommends is using /{apt-cache}/. For example: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +In this example we found out that we had to re-include several packages recommended by live-config and live-boot: #{user-setup}# to make autologin work and #{sudo}# as an essential program to shutdown the system. Besides, it could be handy to add #{live-tools}# to be able to copy the image to RAM and #{eject}# to eventually eject the live medium. So: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# and put a custom #{.xsession}# in it for the default user that will launch /{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a server at #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Build the image: + +code{ + + # lb build + +}code + +Enjoy. + +2~ A base image for a 128MB USB key + +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. + +When optimizing an image to fit a certain media size, you need to understand the tradeoffs you are making between size and functionality. In this example, we trim only so much as to make room for additional material within a 128MB media size, but without doing anything to destroy the integrity of the packages contained within, such as the purging of locale data via the /{localepurge}/ package, or other such "intrusive" optimizations. Of particular note, we use #{--debootstrap-options}# to create a minimal system from scratch. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +To make the image work properly, we must re-add, at least, two recommended packages which are left out by the #{--apt-recommends false}# option. See {Tweaking APT to save space}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Now, build the image in the usual way: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration produced a 110MB image. This compares favourably with the 192MB image produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount of space, the tradeoff being that you need to do an #{apt-get update}# before using /{apt}/ in the live system. Dropping recommended packages with #{--apt-recommends false}# saves some additional space, at the expense of omitting some packages you might otherwise expect to be there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal system from the start. Not automatically including firmware packages with #{--firmware-chroot false}# saves some space too. And finally, #{--memtest none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ A localized GNOME desktop and installer + +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. + +We want to make an iso-hybrid image for i386 architecture using our preferred desktop, in this case GNOME, containing all of the same packages that would be installed by the standard Debian installer for GNOME. + +Our initial problem is the discovery of the names of the appropriate language tasks. Currently, live-build cannot help with this. While we might get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, which can be used to dig it out of the task descriptions in tasksel-data, so to prepare, make sure you have both of those things: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Now we can search for the appropriate tasks, first with: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +By this command, we discover the task is called, plainly enough, german. Now to find the related tasks: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +At boot time we will generate the *{de_CH.UTF-8}* locale and select the *{ch}* keyboard layout. Now let's put the pieces together. Recalling from {Using metapackages}#using-metapackages that task metapackages are prefixed #{task-}#, we just specify these language boot parameters, then add standard priority packages and all our discovered task metapackages to our package list as follows: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to launch the installer from the live desktop. The #{586}# kernel flavour, which is currently necessary for the launcher to work properly, will be included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/en/live-manual.ssm new file mode 100644 index 0000000..35d8893 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Live Systems Manual" + +creator: + author: "Live Systems Project <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." + +date: + published: "2015-08-23" + +publisher: "Live Systems Project <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "`[$]{2}[{]stable[}]`,'stretch' `[$]{2}[{]testing[}]`,'buster' `[$]{2}[{]project[}]`,'Live Systems Project'" + +:A~ @title + +:B~ About + +<< about_manual.ssi + +<< about_project.ssi + +:B~ User + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Project + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Examples + +<< examples.ssi + +:B~ Appendix + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/en/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/en/project_bugs.ssi new file mode 100644 index 0000000..8bf2f24 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/project_bugs.ssi @@ -0,0 +1,119 @@ +:B~ Reporting bugs + +1~bugs Reporting bugs + +Live systems are far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug. It is better to fill a report twice than never. However, this chapter includes recommendations on how to file good bug reports. + +For the impatient: + +_* Always check first the image status updates on our homepage at http://live-systems.org/ for known issues. + +_* Before submitting a bug report always try to reproduce the bug with the *{most recent versions}* of the branch of live-build, live-boot, live-config and live-tools that you're using (like the newest 4.x version of live-build if you're using live-build 4). + +_* Try to give *{as specific information as possible}* about the bug. This includes (at least) the version of live-build, live-boot, live-config, and live-tools used and the distribution of the live system you are building. + +2~ Known issues + +Since Debian *{testing}* and Debian *{unstable}* distributions are moving targets, when you specify either of them as the target system distribution, a successful build may not always be possible. + +% FIXME: + +If this causes too much difficulty for you, do not build a system based on *{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always defaults to the *{stable}* release. + +Currently known issues are listed under the section 'status' on our homepage at http://live-systems.org/. + +It is out of the scope of this manual to train you to correctly identify and fix problems in packages of the development distributions, however, there are two things you can always try: If a build fails when the target distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work either, revert to *{testing}* and pin the newer version of the failing package from *{unstable}* (see {APT pinning}#apt-pinning for details). + +2~ Rebuild from scratch + +To ensure that a particular bug is not caused by an uncleanly built system, please always rebuild the whole live system from scratch to see if the bug is reproducible. + +2~ Use up-to-date packages + +Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. Make sure your build system is up-to-date and any packages included in your image are up-to-date as well. + +2~collect-information Collect information + +Please provide enough information with your report. Include, at least, the exact version of live-build where the bug is encountered and the steps to reproduce it. Please use your common sense and provide any other relevant information if you think that it might help in solving the problem. + +To make the most out of your bug report, we require at least the following information: + +_* Architecture of the host system + +_* Distribution of the host system + +_* Version of live-build on the host system + +_* Version of /{debootstrap}/ on the host system + +_* Architecture of the live system + +_* Distribution of the live system + +_* Version of live-boot on the live system + +_* Version of live-config on the live system + +_* Version of live-tools on the live system + +You can generate a log of the build process by using the #{tee}# command. We recommend doing this automatically with an #{auto/build}# script (see {Managing a configuration}#managing-a-configuration for details). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +At boot time, live-boot and live-config store their logfiles in #{/var/log/live/}#. Check them for error messages. + +Additionally, to rule out other errors, it is always a good idea to tar up your #{config/}# directory and upload it somewhere (do *{not}* send it as an attachment to the mailing list), so that we can try to reproduce the errors you encountered. If this is difficult (e.g. due to size) you can use the output of #{lb config --dump}# which produces a summary of your config tree (i.e. lists files in subdirectories of #{config/}# but does not include them). + +Remember to send in any logs that were produced with English locale settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or #{LC_ALL=en_US}#. + +2~ Isolate the failing case if possible + +If possible, isolate the failing case to the smallest possible change that breaks. It is not always easy to do this so if you cannot manage it for your report, do not worry. However, if you plan your development cycle well, using small enough change sets per iteration, you may be able to isolate the problem by constructing a simpler 'base' configuration that closely matches your actual configuration plus just the broken change set added to it. If you have a hard time sorting out which of your changes broke, it may be that you are including too much in each change set and should develop in smaller increments. + +2~ Use the correct package to report the bug against + +If you do not know what component is responsible for the bug or if the bug is a general bug concerning live systems, you can fill a bug against the debian-live pseudo-package. + +However, we would appreciate it if you try to narrow it down according to where the bug appears. + +3~ At build time while bootstrapping + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to the bootstrapping tool itself. + +In both cases, this is not a bug in the live system, but rather in Debian itself and probably we cannot fix it directly. Please report such a bug against the bootstrapping tool or the failing package. + +3~ At build time while installing packages + +live-build installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system. + +If this is the case, this is not a bug in the live system, but rather in Debian - please report it against the failing package. Running /{debootstrap}/ separately from the Live system build or running #{lb bootstrap --debug}# will give you more information. + +Also, if you are using a local mirror and/or any sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror. + +3~ At boot time + +If your image does not boot, please report it to the mailing list together with the information requested in {Collect information}#collect-information. Do not forget to mention, how/when the image failed exactly, whether using virtualization or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful. + +3~ At run time + +If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in the live system. However: + +2~ Do the research + +Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem. There is always a chance that it has been discussed elsewhere and a possible solution, patch, or workaround has been proposed. + +You should pay particular attention to the live systems mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report. + +In addition, you should check the current bug lists for live-build, live-boot, live-config and live-tools to see whether something similar has already been reported. + +2~ Where to report bugs + +The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For information on how to use the system, please see https://bugs.debian.org/. You can also submit the bugs by using the #{reportbug}# command from the package with the same name. + +In general, you should report build time errors against the live-build package, boot time errors against live-boot, and run time errors against live-config. If you are unsure of which package is appropriate or need more help before submitting a bug report, please report it against the debian-live pseudo-package. We will then take care about it and reassign it where appropriate. + +Please note that bugs found in distributions derived from Debian (such as Ubuntu and others) should *{not}* be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/en/project_coding-style.ssi new file mode 100644 index 0000000..9a03971 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/project_coding-style.ssi @@ -0,0 +1,139 @@ +:B~ Coding Style + +1~coding-style Coding Style + +This chapter documents the coding style used in live systems. + +2~ Compatibility + +_* Don't use syntax or semantics that are unique to the Bash shell. For example, the use of array constructs. + +_* Only use the POSIX subset - for example, use $(foo) over `foo`. + +_* You can check your scripts with 'sh -n' and 'checkbashisms'. + +_* Make sure all shell code runs with 'set -e'. + +2~ Indenting + +_* Always use tabs over spaces. + +2~ Wrapping + +_* Generally, lines are 80 chars at maximum. + +_* Use the "Linux style" of line breaks: + +Bad: + +code{ + + if foo; then + bar + fi + +}code + +Good: + +code{ + + if foo + then + bar + fi + +}code + +_* The same holds for functions: + +Bad: + +code{ + + Foo () { + bar + } + +}code + +Good: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Variables are always in capital letters. + +_* Variables used in live-build always start with #{LB_}# prefix. + +_* Internal temporary variables in live-build should start with the #{\_LB_}# prefix. + +_* Local variables start with live-build #{\_\_LB_}# prefix. + +_* Variables in connection to a boot parameter in live-config start with #{LIVE_}#. + +_* All other variables in live-config start with #{_}# prefix. + +_* Use braces around variables; e.g. write #{${FOO}}# instead of #{$FOO}#. + +_* Always protect variables with quotes to respect potential whitespaces: write #{"${FOO}"}# not #{${FOO}}#. + +_* For consistency reasons, always use quotes when assigning values to variables: + +Bad: + +code{ + + FOO=bar + +}code + +Good: + +code{ + + FOO="bar" + +}code + +_* If multiple variables are used, quote the full expression: + +Bad: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Good: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscellaneous + +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, e.g. "#{sed -e 's|foo|bar|'}#" (without ""). + +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" "#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test -x /bin/foo; ...}#". + +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and faster in execution. + +_* Use capitalized names for functions to limit messing with the users environment. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/en/project_contributing.ssi new file mode 100644 index 0000000..1352b1b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/project_contributing.ssi @@ -0,0 +1,90 @@ +:B~ Contributing to the project + +1~contributing-to-project Contributing to the project + +When submitting a contribution, please clearly identify its copyright holder and include any applicable licensing statement. Note that to be accepted, the contribution must be licensed under the same license as the rest of the documents, namely, GPL version 3 or later. + +Contributions to the project, such as translations and patches, are greatly welcome. Anyone can directly commit to the repositories, however, we ask you to send bigger changes to the mailing list to discuss them first. See the section {Contact}#contact for more information. + +The ${project} uses Git as version control system and source code management. As explained in {Git repositories}#git-repositories there are two main development branches: *{debian}* and *{debian-next}*. Everybody can commit to the debian-next branches of the live-boot, live-build, live-config, live-images, live-manual and live-tools repositories. + +However, there are certain restrictions. The server will reject: + +_* Non fast-forward pushes. + +_* Merge commits. + +_* Adding or removing tags or branches. + +Even though all commits might be revised, we ask you to use your common sense and make good commits with good commit messages. + +_* Write commit messages that consist of complete, meaningful sentences in English, starting with a capital letter and ending with a full stop. Usually, these will start with the form "Fixing/Adding/Removing/Correcting/Translating/...". + +_* Write good commit messages. The first line must be an accurate summary of the contents of the commit which will be included in the changelog. If you need to make some further explanations, write them below leaving a blank line after the first one and then another blank line after each paragraph. Lines of paragraphs should not exceed 80 characters in length. + +_* Commit atomically, this is to say, do not mix unrelated things in the same commit. Make one different commit for each change you make. + +2~ Making changes + +In order to push to the repositories, you must follow the following procedure. Here we use live-manual as an example so replace it with the name of the repository you want to work with. For detailed information on how to edit live-manual see {Contributing to this document}#how-to-contribute. + +_* Fetch the public commit key: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Add the following section to your openssh-client config: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Check out a clone of live-manual through ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Make sure you have Git author and email set: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Important:}* Remember that you should commit any changes on the *{debian-next}* branch. + +_* Make your changes. In this example you would first write a new section dealing with applying patches and then prepare to commit adding the files and writing your commit message like this: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Push the commit to the server: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/en/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/en/project_git.ssi new file mode 100644 index 0000000..174e73b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/project_git.ssi @@ -0,0 +1,61 @@ +:B~ Git repositories + +1~git-repositories Git repositories + +The list of all the available repositories of the ${project} can be found at http://live-systems.org/gitweb/. The project's git URLs have the form: #{protocol://live-systems.org/git/repository}#. Thus, in order to clone live-manual read-only, launch: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +The cloning addresses with write permission have the form: #{git@live-systems.org:/repository}#. + +So, again, to clone live-manual over ssh you must type: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +The git tree is made up of several different branches. The *{debian}* and the *{debian-next}* branches are particularly noteworthy because they contain the actual work that will eventually be included in each new release. + +After cloning any of the existing repositories, you will be on the *{debian}* branch. This is appropriate to take a look at the state of the project's latest release but before starting work it is crucial to switch to the *{debian-next}* branch. To do so: + +code{ + + $ git checkout debian-next + +}code + +The *{debian-next}* branch, which is not always fast-forward, is where all the changes are committed first before being merged into the *{debian}* branch. To make an analogy, it is like a testing ground. If you are working on this branch and need to pull, you will have to do a #{git pull --rebase}# so that your local modifications are staged while pulling from the server and then your changes will be put on top of it all. + +2~ Handling multiple repositories + +If you intend to clone several of the live systems repositories and want to switch to the *{debian-next}* branch right away to check the latest code, write a patch or contribute with a translation you ought to know that the git server provides a #{mrconfig}# file to ease the handling of multiple repositories. In order to use it you need to install the /{mr}/ package and after that, launch: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +This command will automatically clone and checkout to the *{debian-next}* branch the development repositories of the Debian packages produced by the project. These include, among others, the live-images repository, which contains the configurations used for the prebuilt images that the project publishes for general use. For more information on how to use this repository, see {Clone a configuration published via Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/en/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/en/project_procedures.ssi new file mode 100644 index 0000000..ab59df9 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/project_procedures.ssi @@ -0,0 +1,92 @@ +:B~ Procedures + +1~procedures Procedures + +This chapter documents the procedures within the ${project} for various tasks that need cooperation with other teams in Debian. + +2~ Major Releases + +Releasing a new stable major version of Debian includes a lot of different teams working together to make it happen. At some point, the Live team comes in and builds live system images. The requirements to do this are: + +_* A mirror containing the released versions for the debian and debian-security archives which the debian-live buildd can access. + +_* The names of the image need to be known (e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* The data from debian-cd needs to be synced (udeb exclude lists). + +_* Images are built and mirrored on cdimage.debian.org. + +2~ Point Releases + +_* Again, we need updated mirrors of debian and debian-security. + +_* Images are built and mirrored on cdimage.debian.org. + +_* Send announcement mail. + +3~ Last Point Release of a Debian Release + +Remember to adjust both chroot and binary mirrors when building the last set of +images for a Debian release after it has been moved away from ftp.debian.org to +archive.debian.org. That way, old prebuilt live images are still useful without +user modifications. + +3~ Point release announcement template + +An announcement mail for point releases can be generated using the template below and the following command: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Please check the mail carefully before sending and pass it to others for proof-reading. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_basics.ssi new file mode 100644 index 0000000..57d0d97 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_basics.ssi @@ -0,0 +1,411 @@ +:B~ The basics + +1~the-basics The basics + +This chapter contains a brief overview of the build process and instructions for using the three most commonly used image types. The most versatile image type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or USB portable storage device. In certain special cases, as explained later, the #{hdd}# type may be more suitable. The chapter includes detailed instructions for building and using a #{netboot}# type image, which is a bit more involved due to the setup required on the server. This is an slightly advanced topic for anyone who is not already familiar with netbooting, but it is included here because once the setup is done, it is a very convenient way to test and deploy images for booting on the local network without the hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting which is, perhaps, the easiest way of using different images for different purposes, switching from one to the other as needed using the internet as a means. + +Throughout the chapter, we will often refer to the default filenames produced by live-build. If you are {downloading a prebuilt image}#downloading-prebuilt-images instead, the actual filenames may vary. + +2~what-is-live What is a live system? + +A live system usually means an operating system booted on a computer from a removable medium, such as a CD-ROM or USB stick, or from a network, ready to use without any installation on the usual drive(s), with auto-configuration done at run time (see {Terms}#terms). + +With live systems, it's an operating system, built for one of the supported architectures (currently amd64 and i386). It is made from the following parts: + +_* *{Linux kernel image}*, usually named #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux boot, containing modules possibly needed to mount the System image and some scripts to do it. + +_* *{System image}*: The operating system's filesystem image. Usually, a SquashFS compressed filesystem is used to minimize the live system image size. Note that it is read-only. So, during boot the live system will use a RAM disk and 'union' mechanism to enable writing files within the running system. However, all modifications will be lost upon shutdown unless optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen medium, possibly presenting a prompt or menu to allow selection of options/configuration. It loads the Linux kernel and its initrd to run with an associated system filesystem. Different solutions can be used, depending on the target medium and format of the filesystem containing the previously mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, extlinux for ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 partitions, etc. + +You can use live-build to build the system image from your specifications, set up a Linux kernel, its initrd, and a bootloader to run them, all in one medium-dependant format (ISO9660 image, disk image, etc.). + +2~downloading-prebuilt-images Downloading prebuilt images + +While the focus of this manual is developing and building your own live images, you may simply wish to try one of our prebuilt images, either as an introduction to their use or instead of building your own. These images are built using our {live-images git repository}#clone-configuration-via-git and official stable releases are published at https://www.debian.org/CD/live/. In addition, older and upcoming releases, and unofficial images containing non-free firmware and drivers are available at http://live-systems.org/cdimage/release/. + +2~using-web-builder Using the web live image builder + +As a service to the community, we run a web-based live image builder service at http://live-systems.org/build/. This site is maintained on a best effort basis. That is, although we strive to keep it up-to-date and operational at all times, and do issue notices for significant operational outages, we cannot guarantee 100% availability or fast image building, and the service may occasionally have issues that take some time to resolve. If you have problems or questions about the service, please {contact us}#contact, providing us with the link to your build. + +3~ Web builder usage and caveats + +The web interface currently makes no provision to prevent the use of invalid combinations of options, and in particular, where changing an option would normally (i.e. using live-build directly) change defaults of other options listed in the web form, the web builder does not change these defaults. Most notably, if you change #{--architectures}# from the default #{i386}# to #{amd64}#, you must change the corresponding option #{--linux-flavours}# from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for the version of live-build installed on the web builder for more details. The version number of live-build is listed at the bottom of the web builder page. + +The time estimate given by the web builder is a crude estimate only and may not reflect how long your build actually takes. Nor is the estimate updated once it is displayed. Please be patient. Do not refresh the page you land on after submitting the build, as this will resubmit a new build with the same parameters. You should {contact us}#contact if you don't receive notification of your build only once you are certain you've waited long enough and verified the notification e-mail did not get caught by your own e-mail spam filter. + +The web builder is limited in the kinds of images it can build. This keeps it simple and efficient to use and maintain. If you would like to make customizations that are not provided for by the web interface, the rest of this manual explains how to build your own images using live-build. + +2~building-iso-hybrid First steps: building an ISO hybrid image + +Regardless of the image type, you will need to perform the same basic steps to build an image each time. As a first example, create a build directory, change to that directory and then execute the following sequence of live-build commands to create a basic ISO hybrid image containing a default live system without X.org. It is suitable for burning to CD or DVD media, and also to copy onto a USB stick. + +The name of the working directory is absolutely up to you, but if you take a look at the examples used throughout live-manual, it is a good idea to use a name that helps you identify the image you are working with in each directory, especially if you are working or experimenting with different image types. In this case you are going to build a default system so let's call it, for example, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their various options will be used. See {The lb config command}#lb-config for more details. + +Now that the "config/" hierarchy exists, build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and your network connection. When it is complete, there should be a #{live-image-i386.hybrid.iso}# image file, ready to use, in the current directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Using an ISO hybrid live image + +After either building or downloading an ISO hybrid image, which can be obtained at https://www.debian.org/CD/live/, the usual next step is to prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or a USB stick. + +3~burning-iso-image Burning an ISO image to a physical medium + +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the command-line to burn the image. For instance: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copying an ISO hybrid image to a USB stick + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick with the #{cp}# program or an equivalent. Plug in a USB stick with a size large enough for your image file and determine which device it is, which we hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find the right device name by looking in #{dmesg}#'s output after plugging in the stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# command to copy the image to the stick. +*{This will definitely overwrite any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Using the space left on a USB stick + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first partition on the device will be filled up by the live system. To use the remaining free space, use a partitioning tool such as /{gparted}/ or /{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +After the partition is created, where #{${PARTITION}}# is the name of the partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One possible choice would be ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-medium Booting the live medium + +The first time you boot your live medium, whether CD, DVD, USB key, or PXE boot, some setup in your computer's BIOS may be needed first. Since BIOSes vary greatly in features and key bindings, we cannot get into the topic in depth here. Some BIOSes provide a key to bring up a menu of boot devices at boot time, which is the easiest way if it is available on your system. Otherwise, you need to enter the BIOS configuration menu and change the boot order to place the boot device for the live system before your normal boot device. + +Once you've booted the medium, you are presented with a boot menu. If you just press enter here, the system will boot using the default entry, #{Live}# and default options. For more information about boot options, see the "help" entry in the menu and also the live-boot and live-config man pages found within the live system. + +Assuming you've selected #{Live}# and booted a default desktop live image, after the boot messages scroll by, you should be automatically logged into the #{user}# account and see a desktop, ready to use. If you have booted a console-only image, such as a #{standard}# flavour {prebuilt image}#downloading-prebuilt-images, you should be automatically logged in on the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Using a virtual machine for testing + +It can be a great time-saver for the development of live images to run them in a virtual machine (VM). This is not without its caveats: + +_* Running a VM requires enough RAM for both the guest OS and the host and a CPU with hardware support for virtualization is recommended. + +_* There are some inherent limitations to running on a VM, e.g. poor video performance, limited choice of emulated hardware. + +_* When developing for specific hardware, there is no substitute for running on the hardware itself. + +_* Occasionally there are bugs that relate only to running in a VM. When in doubt, test your image directly on the hardware. + +Provided you can work within these constraints, survey the available VM software and choose one that is suitable for your needs. + +3~testing-iso-with-qemu Testing an ISO image with QEMU + +The most versatile VM in Debian is QEMU. If your processor has hardware support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ package description briefly lists the requirements. + +First, install /{qemu-kvm}/ if your processor supports it. If not, install /{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in the following examples. The /{qemu-utils}/ package is also valuable for creating virtual disk images with #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Booting an ISO image is simple: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +See the man pages for more details. + +3~testing-iso-with-virtualbox Testing an ISO image with VirtualBox + +In order to test the ISO with /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use #{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +In order to make the dkms package work, also the kernel headers for the kernel flavour used in your image need to be installed. Instead of manually listing the correct /{linux-headers}/ package in above created package list, the selection of the right package can be done automatically by live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Building and using an HDD image + +Building an HDD image is similar to an ISO hybrid one in all respects except you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# which cannot be burnt to optical media. It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices. Normally, an ISO hybrid image can be used for this purpose instead, but if you have a BIOS which does not handle hybrid images properly, you need an HDD image. + +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Run the #{lb config}# command as before, except this time specifying the HDD image type: + +code{ + + $ lb config -b hdd + +}code + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in the current directory. + +The generated binary image contains a VFAT partition and the syslinux bootloader, ready to be directly written on a USB device. Once again, using an HDD image is just like using an ISO hybrid one on USB. Follow the instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except use the filename #{live-image-i386.img}# instead of #{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run #{kvm}# or #{qemu}#, depending on which version your host system needs, specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Building a netboot image + +The following sequence of commands will create a basic netboot image containing a default live system without X.org. It is suitable for booting over the network. + +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean up the necessary stages. The cause for this is that in netboot setups, a different initramfs configuration needs to be used which live-build performs automatically when building netboot images. Since the initramfs creation belongs to the chroot stage, switching to netboot in an existing build directory means to rebuild the chroot stage too. Therefore, #{lb clean}# (which will remove the chroot stage, too) needs to be used. + +Run the #{lb config}# command as follows to configure your image for netbooting: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +In contrast with the ISO and HDD images, netbooting does not, itself, serve the filesystem image to the client, so the files must be served via NFS. Different network filesystems can be chosen through lb config. The #{--net-root-path}# and #{--net-root-server}# options specify the location and server, respectively, of the NFS server where the filesystem image will be located at boot time. Make sure these are set to suitable values for your network and server. + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +In a network boot, the client runs a small piece of software which usually resides on the EPROM of the Ethernet card. This program sends a DHCP request to get an IP address and information about what to do next. Typically, the next step is getting a higher level bootloader via the TFTP protocol. That could be pxelinux, GRUB, or even boot directly to an operating system like Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# archive in the #{/srv/debian-live}# directory, you'll find the filesystem image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the DHCP server, the TFTP server and the NFS server. + +3~ DHCP server + +We must configure our network's DHCP server to be sure to give an IP address to the netbooting client system, and to advertise the location of the PXE bootloader. + +Here is an example for inspiration, written for the ISC DHCP server #{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ TFTP server + +This serves the kernel and initial ramdisk to the system at run time. + +You should install the /{tftpd-hpa}/ package. It can serve all files contained inside a root directory, usually #{/srv/tftp}#. To let it serve files inside #{/srv/debian-live/tftpboot}#, run as root the following command: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +and fill in the new tftp server directory when being asked about it. + +3~ NFS server + +Once the guest computer has downloaded and booted a Linux kernel and loaded its initrd, it will try to mount the Live filesystem image through a NFS server. + +You need to install the /{nfs-kernel-server}/ package. + +Then, make the filesystem image available through NFS by adding a line like the following to #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +and tell the NFS server about this new export with the following command: + +code{ + + # exportfs -rv + +}code + +Setting up these three services can be a little tricky. You might need some patience to get all of them working together. For more information, see the syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the Debian Installer Manual's TFTP Net Booting section at http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, as their processes are very similar. + +3~ Netboot testing HowTo + +Netboot image creation is made easy with live-build, but testing the images on physical machines can be really time consuming. + +To make our life easier, we can use virtualization. + +3~ Qemu + +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Edit #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Get, or build a #{grub-floppy-netboot}#. + +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using the internet as a means. The requirements for webbooting are very few. On the one hand, you need a medium with a bootloader, an initial ramdisk and a kernel. On the other hand, a web server to store the squashfs files which contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which are available on the project's homepage at http://live-systems.org/. Using prebuilt images would be handy for doing initial testing until one can fine tune their own needs. If you have built a live image you will find the files needed for webbooting in the build directory under #{binary/live/}#. The files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific case, it would be #{/mnt/live/}#. This method has the disadvantage that you need to be root to be able to mount the image. However, it has the advantage that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image and uploading it to the web server at the same time, is using the midnight commander or /{mc}/. If you have the /{genisoimage}/ package installed, the two-pane file manager allows you to browse the contents of an iso file in one pane and upload the files via ftp in the other pane. Even though this method requires manual work, it does not require root privileges. + +3~ Booting webboot images + +While some users will prefer virtualization to test webbooting, we refer to real hardware here to match the following possible use case which should only be considered as an example. + +In order to boot a webboot image it is enough to have the components mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a directory named #{live/}# and install syslinux as bootloader. Then boot from the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot options. live-boot will retrieve the squashfs file and store it into ram. This way, it is possible to use the downloaded compressed filesystem as a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-binary.ssi new file mode 100644 index 0000000..75a4a90 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-binary.ssi @@ -0,0 +1,36 @@ +:B~ Customizing the binary image + +1~customizing-binary Customizing the binary image + +2~ Bootloaders + +live-build uses /{syslinux}/ and some of its derivatives (depending on the image type) as bootloaders by default. They can be easily customized to suit your needs. + +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# into #{config/bootloaders}# and edit the files in there. If you do not want to bother modifying all supported bootloader configurations, only providing a local customized copy of one of the bootloaders, e.g. *{isolinux}* in #{config/bootloaders/isolinux}# is enough too, depending on your use case. + +When modifying one of the default themes, if you want to use a personalized background image that will be displayed together with the boot menu, add a splash.png picture of 640x480 pixels. Then, remove the splash.svg file. + +There are many possibilities when it comes to making changes. For instance, syslinux derivatives are configured by default with a timeout of 0 (zero) which means that they will pause indefinitely at their splash screen until you press a key. + +To modify the boot timeout of a default #{iso-hybrid}# image just edit a default *{isolinux.cfg}* file specifying the timeout in units of 1/10 seconds. A modified *{isolinux.cfg}* to boot after five seconds would be similar to this: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ ISO metadata + +When creating an ISO9660 binary image, you can use the following options to add various textual metadata for your image. This can help you easily identify the version or configuration of an image without booting it. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the application that will be on the image. The maximum length for this field is 128 characters. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the preparer of the image, usually with some contact details. The default for this option is the live-build version you are using, which may help with debugging later. The maximum length for this field is 128 characters. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of the image. This is used as a user-visible label on some platforms such as Windows and Apple Mac OS. The maximum length for this field is 32 characters. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-contents.ssi new file mode 100644 index 0000000..cb963cb --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-contents.ssi @@ -0,0 +1,78 @@ +:B~ Customizing contents + +1~customizing-contents Customizing contents + +This chapter discusses fine-tuning customization of the live system contents beyond merely choosing which packages to include. Includes allow you to add or replace arbitrary files in your live system image, hooks allow you to execute arbitrary commands at different stages of the build and at boot time, and preseeding allows you to configure packages when they are installed by supplying answers to debconf questions. + +2~includes Includes + +While ideally a live system would include files entirely provided by unmodified packages, it is sometimes convenient to provide or modify some content by means of files. Using includes, it is possible to add (or replace) arbitrary files in your live system image. live-build provides two mechanisms for using them: + +_* Chroot local includes: These allow you to add or replace files to the chroot/Live filesystem. Please see {Live/chroot local includes}#live-chroot-local-includes for more information. + +_* Binary local includes: These allow you to add or replace files in the binary image. Please see {Binary local includes}#binary-local-includes for more information. + +Please see {Terms}#terms for more information about the distinction between the "Live" and "binary" images. + +3~live-chroot-local-includes Live/chroot local includes + +Chroot local includes can be used to add or replace files in the chroot/Live filesystem so that they may be used in the Live system. A typical use is to populate the skeleton user directory (#{/etc/skel}#) used by the Live system to create the live user's home directory. Another is to supply configuration files that can be simply added or replaced in the image without processing; see {Live/chroot local hooks}#live-chroot-local-hooks if processing is needed. + +To include files, simply add them to your #{config/includes.chroot}# directory. This directory corresponds to the root directory #{/}# of the live system. For example, to add a file #{/var/www/index.html}# in the live system, use: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Your configuration will then have the following layout: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Chroot local includes are installed after package installation so that files installed by packages are overwritten. + +3~binary-local-includes Binary local includes + +To include material such as documentation or videos on the medium filesystem so that it is accessible immediately upon insertion of the medium without booting the Live system, you can use binary local includes. This works in a similar fashion to chroot local includes. For example, suppose the files #{~/video_demo.*}# are demo videos of the live system described by and linked to by an HTML index page. Simply copy the material to #{config/includes.binary/}# as follows: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +These files will now appear in the root directory of the live medium. + +2~hooks Hooks + +Hooks allow commands to be performed in the chroot and binary stages of the build in order to customize the image. + +3~live-chroot-local-hooks Live/chroot local hooks + +To run commands in the chroot stage, create a hook script with a #{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run in the chroot after the rest of your chroot configuration has been applied, so remember to ensure your configuration includes all packages and files your hook needs in order to run. See the example chroot hook scripts for various common chroot customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. + +3~boot-time-hooks Boot-time hooks + +To execute commands at boot time, you can supply live-config hooks as explained in the "Customization" section of its man page. Examine live-config's own hooks provided in #{/lib/live/config/}#, noting the sequence numbers. Then provide your own hook prefixed with an appropriate sequence number, either as a chroot local include in #{config/includes.chroot/lib/live/config/}#, or as a custom package as discussed in {Installing modified or third-party packages}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +To run commands in the binary stage, create a hook script with a #{.hook.binary}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run after all other binary commands are run, but before binary_checksums, the very last binary command. The commands in your hook do not run in the chroot, so take care to not modify any files outside of the build tree, or you may damage your build system! See the example binary hook scripts for various common binary customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. + +2~ Preseeding Debconf questions + +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf preseed files and are installed by live-build using #{debconf-set-selections}# during the corresponding stage. + +For more information about debconf, please see #{debconf(7)}# in the /{debconf}/ package. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-installer.ssi new file mode 100644 index 0000000..3b6cf53 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-installer.ssi @@ -0,0 +1,52 @@ +:B~ Customizing Debian Installer + +1~customizing-installer Customizing Debian Installer + +Live system images can be integrated with Debian Installer. There are a number of different types of installation, varying in what is included and how the installer operates. + +Please note the careful use of capital letters when referring to the "Debian Installer" in this section - when used like this we refer explicitly to the official installer for the Debian system, not anything else. It is often seen abbreviated to "d-i". + +2~ Types of Debian Installer + +The three main types of installer are: + +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". + +On such images, Debian is installed by fetching and installing .deb packages using /{debootstrap}/, from local media or some network-based network, resulting in a default Debian system being installed to the hard disk. + +This whole process can be preseeded and customized in a number of ways; see the relevant pages in the Debian Installer manual for more information. Once you have a working preseeding file, live-build can automatically put it in the image and enable it for you. + +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. + +Installation will proceed in an identical fashion to the "normal" installation described above, but at the actual package installation stage, instead of using /{debootstrap}/ to fetch and install packages, the live filesystem image is copied to the target. This is achieved with a special udeb called live-installer. + +After this stage, the Debian Installer continues as normal, installing and configuring items such as bootloaders and local users, etc. + +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. + +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. + +Note that by default, live-build does not include Debian Installer images in the images, it needs to be specifically enabled with #{lb config}#. Also, please note that for the "Desktop" installer to work, the kernel of the live system must match the kernel #{d-i}# uses for the specified architecture. For example: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Customizing Debian Installer by preseeding + +As described in the Debian Installer Manual, Appendix B at https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a way to set answers to questions asked during the installation process, without having to manually enter the answers while the installation is running. This makes it possible to fully automate most types of installation and even offers some features not available during normal installations." This kind of customization is best accomplished with live-build by placing the configuration in a #{preseed.cfg}# file included in #{config/includes.installer/}#. For example, to preseed setting the locale to #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Customizing Debian Installer content + +For experimental or debugging purposes, you might want to include locally built #{d-i}# component udeb packages. Place these in #{config/packages.binary/}# to include them in the image. Additional or replacement files and directories may be included in the installer initrd as well, in a similar fashion to {Live/chroot local includes}#live-chroot-local-includes, by placing the material in #{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-overview.ssi new file mode 100644 index 0000000..765c31d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-overview.ssi @@ -0,0 +1,25 @@ +:B~ Customizing contents + +1~customization-overview Customization overview + +This chapter gives an overview of the various ways in which you may customize a live system. + +2~ Build time vs. boot time configuration + +Live system configuration options are divided into build-time options which are options that are applied at build time and boot-time options which are applied at boot time. Boot-time options are further divided into those occurring early in the boot, applied by the live-boot package, and those that happen later in the boot, applied by live-config. Any boot-time option may be modified by the user by specifying it at the boot prompt. The image may also be built with default boot parameters so users can normally just boot directly to the live system without specifying any options when all of the defaults are suitable. In particular, the argument to #{lb --bootappend-live}# consists of any default kernel command line options for the Live system, such as persistence, keyboard layouts, or timezone. See {Customizing locale and language}#customizing-locale-and-language, for example. + +Build-time configuration options are described in the #{lb config}# man page. Boot-time options are described in the man pages for live-boot and live-config. Although the live-boot and live-config packages are installed within the live system you are building, it is recommended that you also install them on your build system for easy reference when you are working on your configuration. It is safe to do so, as none of the scripts contained within them are executed unless the system is configured as a live system. + +2~stages-of-the-build Stages of the build + +The build process is divided into stages, with various customizations applied in sequence in each. The first stage to run is the *{bootstrap}* stage. This is the initial phase of populating the chroot directory with packages to make a barebones Debian system. This is followed by the *{chroot}* stage, which completes the construction of chroot directory, populating it with all of the packages listed in the configuration, along with any other materials. Most customization of content occurs in this stage. The final stage of preparing the live image is the *{binary}* stage, which builds a bootable image, using the contents of the chroot directory to construct the root filesystem for the Live system, and including the installer and any other additional material on the target medium outside of the Live system's filesystem. After the live image is built, if enabled, the source tarball is built in the *{source}* stage. + +Within each of these stages, there is a particular sequence in which commands are applied. These are arranged in such a way as to ensure customizations can be layered in a reasonable fashion. For example, within the *{chroot}* stage, preseeds are applied before any packages are installed, packages are installed before any locally included files are copied, and hooks are run later, after all of the materials are in place. + +2~ Supplement lb config with files + +Although #{lb config}# creates a skeletal configuration in the #{config/}# directory, to accomplish your goals, you may need to provide additional files in subdirectories of #{config/}#. Depending on where the files are stored in the configuration, they may be copied into the live system's filesystem or into the binary image filesystem, or may provide build-time configurations of the system that would be cumbersome to pass as command-line options. You may include things such as custom lists of packages, custom artwork, or hook scripts to run either at build time or at boot time, boosting the already considerable flexibility of debian-live with code of your own. + +2~ Customization tasks + +The following chapters are organized by the kinds of customization task users typically perform: {Customizing package installation}#customizing-package-installation, {Customizing contents}#customizing-contents and {Customizing locale and language}#customizing-locale-and-language cover just a few of the things you might want to do. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-packages.ssi new file mode 100644 index 0000000..f4df072 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-packages.ssi @@ -0,0 +1,364 @@ +:B~ Customizing package installation + +1~customizing-package-installation Customizing package installation + +Perhaps the most basic customization of a live system is the selection of packages to be included in the image. This chapter guides you through the various build-time options to customize live-build's installation of packages. The broadest choices influencing which packages are available to install in the image are the distribution and archive areas. To ensure decent download speeds, you should choose a nearby distribution mirror. You can also add your own repositories for backports, experimental or custom packages, or include packages directly as files. You can define lists of packages, including metapackages which will install many related packages at once, such as packages for a particular desktop or language. Finally, a number of options give some control over /{apt}/, or if you prefer, /{aptitude}/, at build time when packages are installed. You may find these handy if you use a proxy, want to disable installation of recommended packages to save space, or need to control which versions of packages are installed via APT pinning, to name a few possibilities. + +2~ Package sources + +3~ Distribution, archive areas and mode + +The distribution you choose has the broadest impact on which packages are available to include in your live image. Specify the codename, which defaults to ${testing} for the ${testing} version of live-build. Any current distribution carried in the archive may be specified by its codename here. (See {Terms}#terms for more details.) The #{--distribution}# option not only influences the source of packages within the archive, but also instructs live-build to behave as needed to build each supported distribution. For example, to build against the *{unstable}* release, sid, specify: + +code{ + + $ lb config --distribution sid + +}code + +Within the distribution archive, archive areas are major divisions of the archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only #{main}# contains software that is part of the Debian distribution, hence that is the default. One or more values may be specified, e.g. + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimental support is available for some Debian derivatives through a #{--mode}# option. By default, this option is set to #{debian}# only if you are building on a Debian or on an unknown system. If #{lb config}# is invoked on any of the supported derivatives, it will default to create an image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, the distribution names and archive areas for the specified derivative are supported instead of the ones for Debian. The mode also modifies live-build behaviour to suit the derivatives. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Distribution mirrors + +The Debian archive is replicated across a large network of mirrors around the world so that people in each region can choose a nearby mirror for best download speed. Each of the #{--mirror-*}# options governs which distribution mirror is used at various stages of the build. Recall from {Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is when the chroot is initially populated by /{debootstrap}/ with a minimal system, and the *{chroot}* stage is when the chroot used to construct the live system's filesystem is built. Thus, the corresponding mirror switches are used for those stages, and later, in the *{binary}* stage, the #{--mirror-binary}# and #{--mirror-binary-security}# values are used, superseding any mirrors used in an earlier stage. + +3~distribution-mirrors-build-time Distribution mirrors used at build time + +To set the distribution mirrors used at build time to point at a local mirror, it is sufficient to set #{--mirror-bootstrap}# and #{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the #{--mirror-bootstrap}# value. + +3~ Distribution mirrors used at run time + +The #{--mirror-binary*}# options govern the distribution mirrors placed in the binary image. These may be used to install additional packages while running the live system. The defaults employ #{httpredir.debian.org}#, a service that chooses a geographically close mirror based, among other things, on the user's IP family and the availability of the mirrors. This is a suitable choice when you cannot predict which mirror will be best for all of your users. Or you may specify your own values as shown in the example below. An image built from this configuration would only be suitable for users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Additional repositories + +You may add more repositories, broadening your package choices beyond what is available in your target distribution. These may be, for example, for backports, experimental or custom packages. To configure additional repositories, create #{config/archives/your-repository.list.chroot}#, and/or #{config/archives/your-repository.list.binary}# files. As with the #{--mirror-*}# options, these govern the repositories used in the *{chroot}* stage when building the image, and in the *{binary}* stage, i.e. for use when running the live system. + +For example, #{config/archives/live.list.chroot}# allows you to install packages from the debian-live snapshot repository at live system build time. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +If you add the same line to #{config/archives/live.list.binary}#, the repository will be added to your live system's #{/etc/apt/sources.list.d/}# directory. + +If such files exist, they will be picked up automatically. + +You should also put the GPG key used to sign the repository into #{config/archives/your-repository.key.{binary,chroot}}# files. + +Should you need custom APT pinning, such APT preferences snippets can be placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and will be automatically added to your live system's #{/etc/apt/preferences.d/}# directory. + +2~choosing-packages-to-install Choosing packages to install + +There are a number of ways to choose which packages live-build will install in your image, covering a variety of different needs. You can simply name individual packages to install in a package list. You can also use metapackages in those lists, or select them using package control file fields. And finally, you may place package files in your #{config/}# tree, which is well suited to testing of new or experimental packages before they are available from a repository. + +3~package-lists Package lists + +Package lists are a powerful way of expressing which packages should be installed. The list syntax supports conditional sections which makes it easy to build lists and adapt them for use in multiple configurations. Package names may also be injected into the list using shell helpers at build time. + +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. + +3~using-metapackages Using metapackages + +The simplest way to populate your package list is to use a task metapackage maintained by your distribution. For example: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# 2.x. Unlike predefined lists, task metapackages are not specific to the Live System project. Instead, they are maintained by specialist working groups within the distribution and therefore reflect the consensus of each group about which packages best serve the needs of the intended users. They also cover a much broader range of use cases than the predefined lists they replace. + +All task metapackages are prefixed #{task-}#, so a quick way to determine which are available (though it may contain a handful of false hits that match the name but aren't metapackages) is to match on the package name with: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +In addition to these, you will find other metapackages with various purposes. Some are subsets of broader task packages, like #{gnome-core}#, while others are individual specialized parts of a Debian Pure Blend, such as the #{education-*}# metapackages. To list all metapackages in the archive, install the #{debtags}# package and list all packages with the #{role::metapackage}# tag as follows: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Local package lists + +Whether you list metapackages, individual packages, or a combination of both, all local package lists are stored in #{config/package-lists/}#. Since more than one list can be used, this lends itself well to modular designs. For example, you may decide to devote one list to a particular choice of desktop, another to a collection of related packages that might as easily be used on top of a different desktop. This allows you to experiment with different combinations of sets of packages with a minimum of fuss, sharing common lists between different live image projects. + +Package lists that exist in this directory need to have a #{.list}# suffix in order to be processed, and then an additional stage suffix, #{.chroot}# or #{.binary}# to indicate which stage the list is for. + +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. + +3~ Local binary package lists + +To make a binary stage list, place a file suffixed with #{.list.binary}# in #{config/package-lists/}#. These packages are not installed in the live filesystem, but are included on the live medium under #{pool/}#. You would typically use such a list with one of the non-live installer variants. As mentioned above, if you want this list to be the same as your chroot stage list, simply use the #{.list}# suffix by itself. + +3~generated-package-lists Generated package lists + +It sometimes happens that the best way to compose a list is to generate it with a script. Any line starting with an exclamation point indicates a command to be executed within the chroot when the image is built. For example, one might include the line #{! grep-aptavail -n -sPackage -FPriority standard | sort}# in a package list to produce a sorted list of available packages with #{Priority: standard}#. + +In fact, selecting packages with the #{grep-aptavail}# command (from the #{dctrl-tools}# package) is so useful that #{live-build}# provides a #{Packages}# helper script as a convenience. This script takes two arguments: #{field}# and #{pattern}#. Thus, you can create a list with the following contents: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Using conditionals inside package lists + +Any of the live-build configuration variables stored in #{config/*}# (minus the #{LB_}# prefix) may be used in conditional statements in package lists. Generally, this means any #{lb config}# option uppercased and with dashes changed to underscores. But in practice, it is only the ones that influence package selection that make sense, such as #{DISTRIBUTION}#, #{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. + +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is specified: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +You may test for any one of a number of values, e.g. to install /{memtest86+}/ if either #{--architectures i386}# or #{--architectures amd64}# is specified: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +You may also test against variables that may contain more than one value, e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +The nesting of conditionals is not supported. + +% FIXME: + +3~ Removing packages at install time + +You can list packages in files with #{.list.chroot_live}# and #{.list.chroot_install}# suffixes inside the #{config/package-lists}# directory. If both a live and an install list exist, the packages in the #{.list.chroot_live}# list are removed with a hook after the installation (if the user uses the installer). The packages in the #{.list.chroot_install}# list are present both in the live system and in the installed system. This is a special tweak for the installer and may be useful if you have #{--debian-installer live}# set in your config, and wish to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Desktop and language tasks + +Desktop and language tasks are special cases that need some extra planning and configuration. Live images are different from Debian Installer images in this respect. In the Debian Installer, if the medium was prepared for a particular desktop environment flavour, the corresponding task will be automatically installed. Thus, there are internal #{gnome-desktop}#, #{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for tasks for languages, but the user's language choice during the install influences the selection of corresponding language tasks. + +When developing a desktop live image, the image typically boots directly to a working desktop, the choices of both desktop and default language having been made at build time, not at run time as in the case of the Debian Installer. That's not to say that a live image couldn't be built to support multiple desktops or multiple languages and offer the user a choice, but that is not live-build's default behaviour. + +Because there is no provision made automatically for language tasks, which include such things as language-specific fonts and input-method packages, if you want them, you need to specify them in your configuration. For example, a GNOME desktop image containing support for German might include these task metapackages: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Kernel flavour and version + +One or more kernel flavours will be included in your image by default, depending on the architecture. You can choose different flavours via the #{--linux-flavours}# option. Each flavour is suffixed to the default stub #{linux-image}# to form each metapackage name which in turn depends on an exact kernel package to be included in your image. + +Thus by default, an #{amd64}# architecture image will include the #{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured archives, you can specify a different kernel package name stub with the #{--linux-packages}# option. For example, supposing you are building an #{amd64}# architecture image and add the experimental archive for testing purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Custom kernels + +You can build and include your own custom kernels, so long as they are integrated within the Debian package management system. The live-build system does not support kernels not built as #{.deb}# packages. + +The proper and recommended way to deploy your own kernel packages is to follow the instructions in the #{kernel-handbook}#. Remember to modify the ABI and flavour suffixes appropriately, then include a complete build of the #{linux}# and matching #{linux-latest}# packages in your repository. + +If you opt to build the kernel packages without the matching metapackages, you need to specify an appropriate #{--linux-packages}# stub as discussed in {Kernel flavour and version}#kernel-flavour-and-version. As we explain in {Installing modified or third-party packages}#installing-modified-or-third-party-packages, it is best if you include your custom kernel packages in your own repository, though the alternatives discussed in that section work as well. + +It is beyond the scope of this document to give advice on how to customize your kernel. However, you must at least ensure your configuration satisfies these minimum requirements: + +_* Use an initial ramdisk. + +_* Include the union filesystem module (i.e. usually #{aufs}#). + +_* Include any other filesystem modules required by your configuration (i.e. usually #{squashfs}#). + +2~installing-modified-or-third-party-packages Installing modified or third-party packages + +While it is against the philosophy of a live system, it may sometimes be necessary to build a live system with modified versions of packages that are in the Debian repository. This may be to modify or support additional features, languages and branding, or even to remove elements of existing packages that are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietary functionality. + +This section does not cover advice regarding building or maintaining modified packages. Joachim Breitner's 'How to fork privately' method from http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html may be of interest, however. The creation of bespoke packages is covered in the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ and elsewhere. + +There are two ways of installing modified custom packages: + +_* #{packages.chroot}# + +_* Using a custom APT repository + +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" customizations but has a number of drawbacks, while using a custom APT repository is more time-consuming to set up. + +3~ Using #{packages.chroot}# to install custom packages + +To install a custom package, simply copy it to the #{config/packages.chroot/}# directory. Packages that are inside this directory will be automatically installed into the live system during build - you do not need to specify them elsewhere. + +Packages *{must}* be named in the prescribed way. One simple way to do this is to use #{dpkg-name}#. + +Using #{packages.chroot}# for installation of custom packages has disadvantages: + +_* It is not possible to use secure APT. + +_* You must install all appropriate packages in the #{config/packages.chroot/}# directory. + +_* It does not lend itself to storing live system configurations in revision control. + +3~ Using an APT repository to install custom packages + +Unlike using #{packages.chroot}#, when using a custom APT repository you must ensure that you specify the packages elsewhere. See {Choosing packages to install}#choosing-packages-to-install for details. + +While it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified packages. + +3~ Custom packages and APT + +live-build uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package available in two different repositories with different version numbers, APT will elect to install the package with the higher version number. + +Because of this, you may wish to increment the version number in your custom packages' #{debian/changelog}# files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see {APT pinning}#apt-pinning for more information. + +2~ Configuring APT at build time + +You can configure APT through a number of options applied only at build time. (APT configuration used in the running live system may be configured in the normal way for live system contents, that is, by including the appropriate configurations through #{config/includes.chroot/}#.) For a complete list, look for options starting with #{apt}# in the #{lb_config}# man page. + +3~choosing-apt-or-aptitude Choosing apt or aptitude + +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages at build time. Which utility is used is governed by the #{--apt}# argument to #{lb config}#. Choose the method implementing the preferred behaviour for package installation, the notable difference being how missing packages are handled. + +_* #{apt}#: With this method, if a missing package is specified, the package installation will fail. This is the default setting. + +_* #{aptitude}#: With this method, if a missing package is specified, the package installation will succeed. + +3~ Using a proxy with APT + +One commonly required APT configuration is to deal with building an image behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# or #{--apt-http-proxy}# options as needed, e.g. + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Tweaking APT to save space + +You may find yourself needing to save some space on the image medium, in which case one or the other or both of the following options may be of interest. + +If you don't want to include APT indices in the image, you can omit those with: + +code{ + + $ lb config --apt-indices false + +}code + +This will not influence the entries in #{/etc/apt/sources.list}#, but merely whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is that APT needs those indices in order to operate in the live system, so before performing #{apt-cache search}# or #{apt-get install}#, for instance, the user must #{apt-get update}# first to create those indices. + +If you find the installation of recommended packages bloats your image too much, provided you are prepared to deal with the consequences discussed below, you may disable that default option of APT with: + +code{ + + $ lb config --apt-recommends false + +}code + +The most important consequence of turning off recommends is that #{live-boot}# and #{live-config}# themselves recommend some packages that provide important functionality used by most Live configurations, such as #{user-setup}# which #{live-config}# recommends and is used to create the live user. In all but the most exceptional circumstances you need to add back at least some of these recommends to your package lists or else your image will not work as expected, if at all. Look at the recommended packages for each of the #{live-*}# packages included in your build and if you are not certain you can omit them, add them back into your package lists. + +The more general consequence is that if you don't install recommended packages for any given package, that is, "packages that would be found together with this one in all but unusual installations" (Debian Policy Manual, section 7.2), some packages that users of your Live system actually need may be omitted. Therefore, we suggest you review the difference turning off recommends makes to your packages list (see the #{binary.packages}# file generated by #{lb build}#) and re-include in your list any missing packages that you still want installed. Alternatively, if you find you only want a small number of recommended packages left out, leave recommends enabled and set a negative APT pin priority on selected packages to prevent them from being installed, as explained in {APT pinning}#apt-pinning. + +3~ Passing options to apt or aptitude + +If there is not a #{lb config}# option to alter APT's behaviour in the way you need, use #{--apt-options}# or #{--aptitude-options}# to pass any options through to your configured APT tool. See the man pages for #{apt}# and #{aptitude}# for details. Note that both options have default values that you will need to retain in addition to any overrides you may provide. So, for example, suppose you have included something from #{snapshot.debian.org}# for testing purposes and want to specify #{Acquire::Check-Valid-Until=false}# to make APT happy with the stale #{Release}# file, you would do so as per the following example, appending the new option after the default value #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Please check the man pages to fully understand these options and when to use them. This is an example only and should not be construed as advice to configure your image this way. This option would not be appropriate for, say, a final release of a live image. + +For more complicated APT configurations involving #{apt.conf}# options you might want to create a #{config/apt/apt.conf}# file instead. See also the other #{apt-*}# options for a few convenient shortcuts for frequently needed options. + +3~apt-pinning APT pinning + +For background, please first read the #{apt_preferences(5)}# man page. APT pinning can be configured either for build time, or else for run time. For the former, create #{config/archives/*.pref}#, #{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the latter, create #{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live packages that end up in the binary image to be installed from sid at build time. You need to add sid to your APT sources and pin the live packages from it higher, but all other packages from it lower, than the default priority. Thus, only the packages you want are installed from sid at build time and all others are taken from the target system distribution, ${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Negative pin priorities will prevent a package from being installed, as in the case where you do not want a package that is recommended by another package. Suppose you are building an LXDE image using #{task-lxde-desktop}# in #{config/package-lists/desktop.list.chroot}#, but don't want the user prompted to store wifi passwords in the keyring. This metapackage depends on /{lxde-core}/, which recommends /{gksu}/, which in turn recommends /{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ package. This can be done by adding the following stanza to #{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-runtime.ssi new file mode 100644 index 0000000..f68311d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_customization-runtime.ssi @@ -0,0 +1,290 @@ +:B~ Customizing run time behaviours + +1~customizing-run-time-behaviours Customizing run time behaviours + +All configuration that is done during run time is done by live-config. Here are some of the most common options of live-config that users are interested in. A full list of all possibilities can be found in the man page of live-config. + +2~ Customizing the live user + +One important consideration is that the live user is created by live-boot at boot time, not by live-build at build time. This not only influences where materials relating to the live user are introduced in your build, as discussed in {Live/chroot local includes}#live-chroot-local-includes, but also any groups and permissions associated with the live user. + +You can specify additional groups that the live user will belong to by using any of the possibilities to configure live-config. For example, to add the live user to the #{fuse}# group, you can either add the following file in #{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +or use #{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# as a boot parameter. + +It is also possible to change the default username "user" and the default password "live". If you want to do that for any reason, you can easily achieve it as follows: + +To change the default username you can simply specify it in your config: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +One possible way of changing the default password is by means of a hook as described in {Boot-time hooks}#boot-time-hooks. In order to do that you can use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, prefix it accordingly (e.g. 2000-passwd) and add it to #{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Customizing locale and language + +When the live system boots, language is involved in two steps: + +_* the locale generation + +_* setting the keyboard configuration + +The default locale when building a Live system is #{locales=en_US.UTF-8}#. To define the locale that should be generated, use the #{locales}# parameter in the #{--bootappend-live}# option of #{lb config}#, e.g. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Multiple locales may be specified as a comma-delimited list. + +This parameter, as well as the keyboard configuration parameters indicated below, can also be used at the kernel command line. You can specify a locale by #{language_country}# (in which case the default encoding is used) or the full #{language_country.encoding}# word. A list of supported locales and the encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. + +Both the console and X keyboard configuration are performed by #{live-config}# using the #{console-setup}# package. To configure them, use the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and #{keyboard-model}# boot parameters via the #{--bootappend-live}# option. Valid options for these can be found in #{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a given language, try searching for the English name of the language and/or the country where the language is spoken, e.g: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Note that each variant lists the layout to which it applies in the description. + +Often, only the layout needs to be configured. For example, to get the locale files for German and Swiss German keyboard layout in X use: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +However, for very specific use cases, you may wish to include other parameters. For example, to set up a French system with a French-Dvorak layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Multiple values may be specified as comma-delimited lists for each of the #{keyboard-*}# options, with the exception of #{keyboard-model}#, which accepts only one value. Please see the #{keyboard(5)}# man page for details and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and #{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are given, they will be matched one-to-one with #{keyboard-layouts}# values (see #{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to define two layouts, the default being US QWERTY and the other being US Dvorak, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistence + +A live cd paradigm is a pre-installed system which runs from read-only media, like a cdrom, where writes and modifications do not survive reboots of the host hardware which runs it. + +A live system is a generalization of this paradigm and thus supports other media in addition to CDs; but still, in its default behaviour, it should be considered read-only and all the run-time evolutions of the system are lost at shutdown. + +'Persistence' is a common name for different kinds of solutions for saving across reboots some, or all, of this run-time evolution of the system. To understand how it works it would be handy to know that even if the system is booted and run from read-only media, modifications to the files and directories are written on writable media, typically a ram disk (tmpfs) and ram disks' data do not survive reboots. + +The data stored on this ramdisk should be saved on a writable persistent medium like local storage media, a network share or even a session of a multisession (re)writable CD/DVD. All these media are supported in live systems in different ways, and all but the last one require a special boot parameter to be specified at boot time: #{persistence}#. + +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not set), local storage media (e.g. hard disks, USB drives) will be probed for persistence volumes during boot. It is possible to restrict which types of persistence volumes to use by specifying certain boot parameters described in the live-boot(7) man page. A persistence volume is any of the following: + +_* a partition, identified by its GPT name. + +_* a filesystem, identified by its filesystem label. + +_* an image file located on the root of any readable filesystem (even an NTFS partition of a foreign OS), identified by its filename. + +The volume label for overlays must be #{persistence}# but it will be ignored unless it contains in its root a file named #{persistence.conf}# which is used to fully customize the volume's persistence, this is to say, specifying the directories that you want to save in your persistence volume after a reboot. See {The persistence.conf file}#persistence-conf for more details. + +Here are some examples of how to prepare a volume to be used for persistence. It can be, for instance, an ext4 partition on a hard disk or on a usb key created with, e.g.: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +See also {Using the space left on a USB stick}#using-usb-extra-space. + +If you already have a partition on your device, you could just change the label with one of the following: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Here's an example of how to create an ext4-based image file to be used for persistence: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Once the image file is created, as an example, to make #{/usr}# persistent but only saving the changes you make to that directory and not all the contents of #{/usr}#, you can use the "union" option. If the image file is located in your home directory, copy it to the root of your hard drive's filesystem and mount it in #{/mnt}# as follows: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Then, create the #{persistence.conf}# file adding content and unmount the image file. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Now, reboot into your live medium with the boot parameter "persistence". + +3~persistence-conf The persistence.conf file + +A volume with the label #{persistence}# must be configured by means of the #{persistence.conf}# file to make arbitrary directories persistent. That file, located on the volume's filesystem root, controls which directories it makes persistent, and in which way. + +How custom overlay mounts are configured is described in full detail in the persistence.conf(5) man page, but a simple example should be sufficient for most uses. Let's say we want to make our home directory and APT cache persistent in an ext4 filesystem on the /dev/sdb1 partition: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Then we reboot. During the first boot the contents of #{/home}# and #{/var/cache/apt}# will be copied into the persistence volume, and from then on all changes to these directories will live in the persistence volume. Please note that any paths listed in the #{persistence.conf}# file cannot contain white spaces or the special #{.}# and #{..}# path components. Also, neither #{/lib}#, #{/lib/live}# (or any of their sub-directories) nor #{/}# can be made persistent using custom mounts. As a workaround for this limitation you can add #{/ union}# to your #{persistence.conf}# file to achieve full persistence. + +3~ Using more than one persistence store + +There are different methods of using multiple persistence store for different use cases. For instance, using several volumes at the same time or selecting only one, among various, for very specific purposes. + +Several different custom overlay volumes (with their own #{persistence.conf}# files) can be used at the same time, but if several volumes make the same directory persistent, only one of them will be used. If any two mounts are "nested" (i.e. one is a sub-directory of the other) the parent will be mounted before the child so no mount will be hidden by the other. Nested custom mounts are problematic if they are listed in the same #{persistence.conf}# file. See the persistence.conf(5) man page for how to handle that case if you really need it (hint: you usually don't). + +One possible use case: If you wish to store the user data i.e. #{/home}# and the superuser data i.e. #{/root}# in different partitions, create two partitions with the #{persistence}# label and add a #{persistence.conf}# file in each one like this, #{# echo "/home" > persistence.conf}# for the first partition that will save the user's files and #{# echo "/root" > persistence.conf}# for the second partition which will store the superuser's files. Finally, use the #{persistence}# boot parameter. + +If a user would need multiple persistence store of the same type for different locations or testing, such as #{private}# and #{work}#, the boot parameter #{persistence-label}# used in conjunction with the boot parameter #{persistence}# will allow for multiple but unique persistence media. An example would be if a user wanted to use a persistence partition labeled #{private}# for personal data like browser bookmarks or other types, they would use the boot parameters: #{persistence}# #{persistence-label=private}#. And to store work related data, like documents, research projects or other types, they would use the boot parameters: #{persistence}# #{persistence-label=work}#. + +It is important to remember that each of these volumes, #{private}# and #{work}#, also needs a #{persistence.conf}# file in its root. The live-boot man page contains more information about how to use these labels with legacy names. + +3~ Using persistence with encryption + +Using the persistence feature means that some sensible data might get exposed to risk. Especially if the persistent data is stored on a portable device such as a usb stick or an external hard drive. That is when encryption comes in handy. Even if the entire procedure might seem complicated because of the number of steps to be taken, it is really easy to handle encrypted partitions with live-boot. In order to use *{luks}*, which is the supported encryption type, you need to install /{cryptsetup}/ both on the machine you are creating the encrypted partition with and also in the live system you are going to use the encrypted persistent partition with. + +To install /{cryptsetup}/ on your machine: + +code{ + + # apt-get install cryptsetup + +}code + +To install /{cryptsetup}/ in your live system, add it to your package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Once you have your live system with /{cryptsetup}/, you basically only need to create a new partition, encrypt it and boot with the #{persistence}# and #{persistence-encryption=luks}# parameters. We could have already anticipated this step and added the boot parameters following the usual procedure: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Let's go into the details for all of those who are not familiar with encryption. In the following example we are going to use a partition on a usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need to determine which partition is the one you are going to use in your specific case. + +The first step is plugging in your usb stick and determine which device it is. The recommended method of listing devices in live-manual is using #{ls -l /dev/disk/by-id}#. After that, create a new partition and then, encrypt it with a passphrase as follows: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Then open the luks partition in the virtual device mapper. Use any name you like. We use *{live}* here as an example: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +The next step is filling the device with zeros before creating the filesystem: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Now, we are ready to create the filesystem. Notice that we are adding the label #{persistence}# so that the device is mounted as persistence store at boot time. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +To continue with our setup, we need to mount the device, for example in #{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +And create the #{persistence.conf}# file in the root of the partition. This is, as explained before, strictly necessary. See {The persistence.conf file}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Then unmount the mount point: + +code{ + + # umount /mnt + +}code + +And optionally, although it might be a good way of securing the data we have just added to the partition, we can close the device: + +code{ + + # cryptsetup luksClose live + +}code + +Let's summarize the process. So far, we have created an encryption capable live system, which can be copied to a usb stick as explained in {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also created an encrypted partition, which can be located in the same usb stick to carry it around and we have configured the encrypted partition to be used as persistence store. So now, we only need to boot the live system. At boot time, live-boot will prompt us for the passphrase and will mount the encrypted partition to be used for persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_installation.ssi new file mode 100644 index 0000000..222f4ac --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_installation.ssi @@ -0,0 +1,142 @@ +:B~ Installation + +1~installation Installation + +2~requirements Requirements + +Building live system images has very few system requirements: + +_* Superuser (root) access + +_* An up-to-date version of live-build + +_* A POSIX-compliant shell, such as /{bash}/ or /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6 or newer. + +Note that using Debian or a Debian-derived distribution is not required - live-build will run on almost any distribution with the above requirements. + +2~installing-live-build Installing live-build + +You can install live-build in a number of different ways: + +_* From the Debian repository + +_* From source + +_* From snapshots + +If you are using Debian, the recommended way is to install live-build via the Debian repository. + +3~ From the Debian repository + +Simply install live-build like any other package: + +code{ + + # apt-get install live-build + +}code + +3~ From source + +live-build is developed using the Git version control system. On Debian based systems, this is provided by the /{git}/ package. To check out the latest code, execute: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +You can build and install your own Debian package by executing: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Now install whichever of the freshly built #{.deb}# files you were interested in, e.g. + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +You can also install live-build directly to your system by executing: + +code{ + + # make install + +}code + +and uninstall it with: + +code{ + + # make uninstall + +}code + +3~ From 'snapshots' + +If you do not wish to build or install live-build from source, you can use snapshots. These are built automatically from the latest version in Git and are available on http://live-systems.org/debian/. + +2~ Installing live-boot and live-config + +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. + +3~ From the Debian repository + +Both live-boot and live-config are available from the Debian repository as per {Installing live-build}#installing-live-build. + +3~ From source + +To use the latest source from git, you can follow the process below. Please ensure you are familiar with the terms mentioned in {Terms}#terms. + +_* Checkout the live-boot and live-config sources + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consult the live-boot and live-config man pages for details on customizing if that is your reason for building these packages from source. + +_* Build live-boot and live-config .deb files + +You must build either on your target distribution or in a chroot containing your target platform: this means if your target is ${testing} then you should build against ${testing}. + +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to build live-boot for a target distribution that differs from your build system. For example, for ${testing} live images, build live-boot in a ${testing} chroot. If your target distribution happens to match your build system distribution, you may build directly on the build system using #{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Use applicable generated .deb files + +As live-boot and live-config are installed by live-build system, installing the packages in the host system is not sufficient: you should treat the generated .deb files like any other custom packages. Since your purpose for building from source is likely to test new things over the short term before the official release, follow {Installing modified or third-party packages}#installing-modified-or-third-party-packages to temporarily include the relevant files in your configuration. In particular, notice that both packages are divided into a generic part, a documentation part and one or more back-ends. Include the generic part, only one back-end matching your configuration, and optionally the documentation. Assuming you are building a live image in the current directory and have generated all .deb files for a single version of both packages in the directory above, these bash commands would copy all of the relevant packages including default back-ends: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ From 'snapshots' + +You can let live-build automatically use the latest snapshots of live-boot and live-config by configuring the package repository on live-systems.org as a third-party repository in your live-build configuration directory. diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_managing_a_configuration.ssi new file mode 100644 index 0000000..cdfa9cd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_managing_a_configuration.ssi @@ -0,0 +1,83 @@ +:B~ Managing a configuration + +1~managing-a-configuration Managing a configuration + +This chapter explains how to manage a live configuration from initial creation, through successive revisions and successive releases of both the live-build software and the live image itself. + +2~ Dealing with configuration changes + +Live configurations rarely are perfect on the first try. It may be fine to pass #{lb config}# options from the command-line to perform a single build, but it is more typical to revise those options and build again until you are satisfied. To support these changes, you will need auto scripts which ensure your configuration is kept in a consistent state. + +3~ Why use auto scripts? What do they do? + +The #{lb config}# command stores the options you pass to it in #{config/*}# files along with many other options set to default values. If you run #{lb config}# again, it will not reset any option that was defaulted based on your initial options. So, for example, if you run #{lb config}# again with a new value for #{--binary-images}#, any dependent options that were defaulted for the old image type may no longer work with the new ones. Nor are these files intended to be read or edited. They store values for over a hundred options, so nobody, let alone yourself, will be able to see in these which options you actually specified. And finally, if you run #{lb config}#, then upgrade live-build and it happens to rename an option, #{config/*}# would still contain variables named after the old option that are no longer valid. + +For all these reasons, #{auto/*}# scripts will make your life easier. They are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# commands that are designed to help you manage your configuration. The #{auto/config}# script stores your #{lb config}# command with all desired options, the #{auto/clean}# script removes the files containing configuration variable values, and the #{auto/build}# script keeps a #{build.log}# of each build. Each of these scripts is run automatically every time you run the corresponding #{lb}# command. By using these scripts, your configuration is easier to read and is kept internally consistent from one revision to the next. Also, it will be much easier for you identify and fix options which need to change when you upgrade live-build after reading the updated documentation. + +3~ Use example auto scripts + +For your convenience, live-build comes with example auto shell scripts to copy and edit. Start a new, default configuration, then copy the examples into it: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Edit #{auto/config}#, adding any options as you see fit. For instance: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Now, each time you use #{lb config}#, #{auto/config}# will reset the configuration based on these options. When you want to make changes to them, edit the options in this file instead of passing them to #{lb config}#. When you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files along with any other build products. And finally, when you use #{lb build}#, a log of the build will be written by #{auto/build}# in #{build.log}#. + +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. + +2~clone-configuration-via-git Clone a configuration published via Git + +Use the #{lb config --config}# option to clone a Git repository that contains a live system configuration. If you would like to base your configuration on one maintained by the ${project}, look at http://live-systems.org/gitweb/ for the repository named #{live-images}# in the category #{Packages}#. This repository contains the configurations for the live systems {prebuilt images}#downloading-prebuilt-images. + +For example, to build a standard image, use the #{live-images}# repository as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Edit #{auto/config}# and any other things you need in the #{config}# tree to suit your needs. For example, the unofficial non-free prebuilt images are made by simply adding #{--archive-areas "main contrib non-free"}#. + +You may optionally define a shortcut in your Git configuration by adding the following to your #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +This enables you to use #{lso:}# anywhere you need to specify the address of a #{live-systems.org}# git repository. If you also drop the optional #{.git}# suffix, starting a new image using this configuration is as easy as: + +code{ + + $ lb config --config lso:live-images + +}code + +Cloning the entire #{live-images}# repository pulls the configurations used for several images. If you feel like building a different image after you have finished with the first one, change to another directory and again and optionally, make any changes to suit your needs. + +In any case, remember that every time you will have to build the image as superuser: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/en/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/en/user_overview.ssi new file mode 100644 index 0000000..b2fc7bf --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/en/user_overview.ssi @@ -0,0 +1,80 @@ +:B~ Overview of tools + +1~overview-of-tools Overview of tools + +This chapter contains an overview of the three main tools used in building live systems: live-build, live-boot and live-config. + +2~live-build The live-build package + +live-build is a collection of scripts to build live systems. These scripts are also referred to as "commands". + +The idea behind live-build is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image. + +Many concepts are similar to those used to build Debian packages with /{debhelper}/: + +_* The scripts have a central location for configuring their operation. In /{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For example, dh_install will look, among others, for a file called #{debian/install}# to determine which files should exist in a particular binary package. In much the same way, live-build stores its configuration entirely under a #{config/}# subdirectory. + +_* The scripts are independent - that is to say, it is always safe to run each command. + +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton configuration directory. This could be considered to be similar to tools such as /{dh-make}/. For more information about these tools, read on, since the remainder of this section discuses the four most important commands. Note that the preceding #{lb}# is a generic wrapper for live-build commands. + +_* *{lb config}*: Responsible for initializing a Live system configuration directory. See {The lb config command}#lb-config for more information. + +_* *{lb build}*: Responsible for starting a Live system build. See {The lb build command}#lb-build for more information. + +_* *{lb clean}*: Responsible for removing parts of a Live system build. See {The lb clean command}#lb-clean for more information. + +3~lb-config The #{lb config}# command + +As discussed in {live-build}#live-build, the scripts that make up live-build read their configuration with the #{source}# command from a single directory named #{config/}#. As constructing this directory by hand would be time-consuming and error-prone, the #{lb config}# command can be used to create the initial skeleton configuration tree. + +Issuing #{lb config}# without any arguments creates the #{config/}# subdirectory which is populated with some default settings in configuration files, and two skeleton trees named #{auto/}# and #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Using #{lb config}# without any arguments would be suitable for users who need a very basic image, or who intend to provide a more complete configuration via #{auto/config}# later (see {Managing a configuration}#managing-a-configuration for details). + +Normally, you will want to specify some options. For example, to specify which package manager to use while building the image: + +code{ + + $ lb config --apt aptitude + +}code + +It is possible to specify many options, such as: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +A full list of options is available in the #{lb_config}# man page. + +3~lb-build The #{lb build}# command + +The #{lb build}# command reads in your configuration from the #{config/}# directory. It then runs the lower level commands needed to build your Live system. + +3~lb-clean The #{lb clean}# command + +It is the job of the #{lb clean}# command to remove various parts of a build so subsequent builds can start from a clean state. By default, #{chroot}#, #{binary}# and #{source}# stages are cleaned, but the cache is left intact. Also, individual stages can be cleaned. For example, if you have made changes that only affect the binary stage, use #{lb clean --binary}# prior to building a new binary. If your changes invalidate the bootstrap and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or #{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man page for a full list of options. + +2~live-boot The live-boot package + +live-boot is a collection of scripts providing hooks for the /{initramfs-tools}/, used to generate an initramfs capable of booting live systems, such as those created by live-build. This includes the live system ISOs, netboot tarballs, and USB stick images. + +At boot time it will look for read-only media containing a #{/live/}# directory where a root filesystem (often a compressed filesystem image like squashfs) is stored. If found, it will create a writable environment, using aufs, for Debian like systems to boot from. + +More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter on initramfs. + +2~live-config The live-config package + +live-config consists of the scripts that run at boot time after live-boot to configure the live system automatically. It handles such tasks as setting the hostname, locales and timezone, creating the live user, inhibiting cron jobs and performing autologin of the live user. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/es/about_manual.ssi new file mode 100644 index 0000000..c4aabf2 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/about_manual.ssi @@ -0,0 +1,299 @@ +:B~ Acerca de este manual + +1~about-manual Acerca de este manual + +El objetivo principal de este manual es servir como único punto de acceso a +toda la documentación referente al ${project} y en particular al sofware que +el proyecto crea para Debian 9.0 "${stable}". Se puede encontrar siempre una +versión actualizada en http://live-systems.org/ + +live-manual está principalmente enfocado a ayudar en la creación de un +sistema en vivo y no está dirigido al usuario final de estos sistemas. Un +usuario final puede encontrar información útil en las siguentes secciones: +{Conceptos básicos}#the-basics que cubre la descarga de imágenes +prefabricadas y la preparación de imágenes para arrancar un sistema desde un +medio de almacenamiento o desde una red local, ya sea utilizando el +constructor web o ejecutando live-build directamente en el +sistema. {Personalización del comportamiento en tiempo de +ejecución}#customizing-run-time-behaviours que describe algunas de las +opciones que pueden especificarse en el indicador de arranque, como pueden +ser la selección de la distribución del teclado, las variantes locales o la +persistencia. + +Algunos de los comandos mencionados en el texto deben ser ejecutados con +privilegios de superusuario, que pueden ser obtenidos accediendo a la cuenta +de root mediante la orden #{su}# o mediante la orden #{sudo}#. Para +distinguir las ordenes que deben ser ejecutadas como usuario no privilegiado +de las que si requieren privilegios de superusuario se ha prefijado con +#{$}# las primeras y con #{#}# las segundas. Estos símbolos no son parte de +la orden. + +2~ Para el impaciente. + +Aunque se cree que todo lo descrito en este manual es importante para la +mayoría de los usuarios, es cierto que hay mucho material a interiorizar y +que los usuarios desean experimentar con las herramientas de forma rápida y +satisfactoria antes de entrar en detalles. Por lo tanto, se sugiere leer +siguiendo el siguiente orden. + +Primero, leer el capítulo {Acerca de este manual}#about-manual, desde el +principio y terminando en la sección {Términos}#terms. Después, saltar hasta +los tres tutoriales que están al principio de la sección {Ejemplos}#examples +pensados para aprender a configurar y construir imágenes de forma básica. Se +deberá leer primero {Uso de los ejemplos}#using-the-examples, seguido de +{Tutorial 1: Una imagen predeterminada}#tutorial-1 y {Tutorial 2: Una +utilidad de navegador web}#tutorial-2, para finalizar con {Tutorial 3: Una +imagen personalizada}#tutorial-3. Al final de estos tutoriales, el lector +tendrá una visión de lo que se puede hacer con los sistemas en vivo. + +Se anima a profundizar en el estudio del manual con la lectura detenida del +siguiente capítulo: {Conceptos básicos}#the-basics, y de una manera más +somera el capítulo {La creación de una imagen +netboot}#building-netboot-image, para acabar con la lectura de {Descripción +general de la personalización}#customization-overview y los capítulos que le +siguen. Se espera que, en este punto, el lector esté lo suficientemente +motivado con lo que se puede hacer con los sistemas en vivo para leer el +resto del manual, de principio a fin. + +2~terms Términos + +_* *{Sistema en vivo}*: Se entiende por sistema en vivo aquel sistema +operativo que se puede arrancar sin instalación previa en el disco duro. Un +sistema en vivo no altera ningún sistema operativo previamente instalado ni +ningún fichero existente en el disco duro de la máquina a menos que se le +instruya para hacerlo. Los sistemas en vivo son arrancados típicamente desde +medios extraíbles como CDs, DVDs o llaves USB. Algunos pueden también +arrancar desde la red local (utilizando imágenes tipo netboot, ver {Creación +de una imagen de arranque en red}#building-netboot-image), o incluso desde +internet utilizando el parámetro de arranque #{fetch=URL}#, ver {Arrancar +desde internet}#webbooting). + +_* *{Medio en vivo}*: A diferencia de sistema en vivo, el medio en vivo se +refiere al CD, DVD o memoria USB donde se copia el fichero binario producido +por live-build y utilizado para arrancar el sistema en vivo. Más +ampliamente, el término también se refiere a cualquier lugar en el que +reside el fichero binario a los efectos de iniciar el sistema en vivo, tales +como la ubicación de los ficheros de arranque de red. + +_* *{${project}}*: Es un proyecto que mantiene, entre otros, los paquetes +live-boot, live-build, live-config, live-tools y live-manual. + +_* *{Sistema huésped}*: Es el conjunto de herramientas y equipo utilizado +para crear el sistema en vivo. + +_* *{Sistema objetivo}*: Es el conjunto de herramientas y equipo donde se +ejecutará el sistema en vivo. + +_* *{live-boot}*: Es una colección de scripts que serán responsables de +arrancar el sistema en vivo. + +_* *{live-build}*: Una colección de scripts utilizados para construir +sistemas en vivo personalizados. + +_* *{live-config}*: Es una colección de scripts utilizados para configurar +un sistema en vivo durante el proceso de arranque. + +_* *{live-tools}*: Una colección de scripts adicionales que se utilizan para +realizar tareas útiles en un sistema en vivo en ejecución. + +_* *{live-manual}*: Este documento forma parte de un paquete llamado +live-manual. + +_* *{Instalador de Debian (Debian Installer o d-i)}*: Es el mecanismo +oficial de instalación para la distribución Debian. + +_* *{Parámetros de arranque}*: Parámetros que son entregados al gestor de +arranque (bootloader) para modificar el comportamiento del kernel o del +conjunto de scripts live-config. Son llamados también Parámetros de kernel u +Opciones de arranque. + +_* *{chroot}*: El programa /{chroot}/, #{chroot(8)}#, permite ejecutar +diferentes instancias de un entorno GNU/Linux en un solo sistema de manera +simultánea sin necesidad de reiniciar el sistema. + +_* *{Imagen binaria}*: Es un fichero que contiene el sistema en vivo. Su +nombre puede ser, por ejemplo, live-image-i386.hybrid.iso o +live-image-i386.img dependiendo de su formato. + +_* *{Distribución objetivo}*: Es la versión de la distribución Debian en la +cual estará basado el sistema en vivo que puede diferir de la versión de la +distribución en el sistema huésped. + +_* *{stable/testing/unstable}*: La distribución *{stable}*, actualmente +llamada ${stable}, contiene la última distribución Debian publicada +oficialmente. La distribución *{testing}*, temporalmente llamada ${testing}, +está en la rampa de salida para ser la próxima distribución *{stable}*. La +principal ventaja de utilizar esta distribución es que tiene versiones de +programas más recientes si se compara con la versión *{stable}*. La +distribución *{unstable}*, permanentemente llamada sid, es dónde se realiza +el desarrollo de Debian. Generalmente esta distribución es usada por los +desarrolladores y aquellos que les gusta vivir al filo de lo imposible. A lo +largo del manual, se usan sus nombres en clave, como por ejemplo ${testing} +o sid, ya que es lo que las mismas herramientas reconocen. + +2~ Autores + +Lista de autores (en orden alfabético): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Cómo contribuir a este documento + +Este manual se ha creado como un proyecto comunitario y cualquier propuesta +para su mejora u otras contribuciones son siempre bienvenidas. Ver la +sección {Contribuir al proyecto}#contributing-to-project para obtener +información detallada sobre cómo obtener la clave pública y hacer buenos +commits. + +3~applying-changes Aplicar cambios + +Para realizar cambios en el manual en Inglés se debe editar los ficheros +adecuados en #{manual/en/}# pero antes de enviar una contribución se debería +realizar una visualización del trabajo realizado. Para ello asegurarse de +tener instalados los paquetes necesarios para la construcción de live-manual +ejecutando la siguiente orden: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Se puede realizar la construcción del manual posicionándose en el directorio +de nivel superior, o sea, en el directorio clonado mediante Git y ejecutando +la siguiente orden: + +code{ + + $ make build + +}code + +Ya que construir el manual completo en todos los idiomas disponibles cuesta +bastante rato, los autores seguramente estaran interesados en utilizar +alguno de los siguientes atajos a la hora de revisar la documentación que +hayan añadido al manual en inglés. Utilizando #{PROOF=1}# se crea +live-manual en formato html, pero sin los documentos html segmentados, y +utilizando #{PROOF=2}# se crea live-manual en formato pdf pero sólo en +retrato A4 y carta. Por este motivo, utilizar cualquiera de las opciones +#{PROOF=}# puede llegar a ahorrar una cantidad de tiempo considerable, por +ejemplo. + +code{ + + $ make build PROOF=1 + +}code + +Cuando se revisa alguna de las traducciones, es posible construir sólo un +idioma ejecutando, por ejemplo: + +code{ + + $ make build LANGUAGES=de + +}code + +Es posible generar el documento por formato: + +code{ + + $ make build FORMATS=pdf + +}code + +O combinar ambos, por ejemplo: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +Después de revisar el trabajo y asegurarse de que todo está bien, no +ejecutar #{make commit}# a menos de que se actualicen las traducciones al +mismo tiempo, y en ese caso, no mezclar los cambios al manual en inglés con +las traducciones en el mismo commit, sino en commits separados. Ver la +sección {Traducción}#translation para más detalles. + +3~translation Traducción + +Para traducir live-manual, seguir estos pasos, dependiendo de si se está +comenzando una traducción desde cero o si se continua trabajando en una +traducción ya comenzada: + +_* Empezar una nueva traducción desde cero + +_2* Traducir los ficheros *{about_manual.ssi.pot}*, +*{about_project.ssi.pot}* y *{index.html.in.pot}* de #{manual/pot/}# al +idioma deseado con cualquier editor (como puede ser /{poedit}/). Enviar los +ficheros #{.po}# traducidos a la lista de correo para revisar su +integridad. La comprobación de integridad de live-manual no sólo se asegura +de que los ficheros #{.po}# estén 100% traducidos sino que también detecta +posibles errores. + +_2* Una vez comprobados, para activar una nueva lengua en el autobuild basta +con añadir los ficheros traducidos inicialmente a #{manual/po/${LANGUAGE}/}# +y ejecutar #{make commit}#. Y entonces, editar +#{manual/_sisu/home/index.html}# añadiendo el nombre de la lengua y su +nombre en inglés entre paréntesis. + +_* Continuar con una traducción ya comenzada + +_2* Si el nuevo idioma ya ha sido añadido, se puede continuar la traducción +de los ficheros .po restantes en #{manual/po/${LANGUAGE}/}# de manera +aleatoria utilizando el editor preferido (como por ejemplo /{poedit}/). + +_2* No se debe olvidar la ejecución del comando #{make commit}# para +actualizar los manuales traducidos a partir de los ficheros .po. Entonces se +puede revisar los cambios ejecutando #{make build}# antes de #{git add .}#, +#{git commit -m "Translating..."}# y #{git push}#. Recordar que como #{make +build}# puede tardar una cantidad considerable de tiempo, se pueden revisar +las diferentes lenguas de forma individual como se explica en {Aplicar +cambios}#applying-changes + +Después de ejecutar #{make commit}# se podrá observar bastante texto en la +pantalla. Básicamente son mensajes informativos sobre el estado del proceso +y también algunas pistas sobre lo que se puede hacer para mejorar +live-manual. A menos que se vea un error fatal, generalmente se puede +proceder y enviar la contribución. + +live-manual incluye dos utilidades que pueden ser de gran ayuda para los +traductores a la hora de encontrar mensajes sin traducir y mensajes +difusos. La primera es "make translate". Esta activa un script que muestra +en detalle cuántos mensajes sin traducir hay en cada fichero .po. La +segunda, "make fixfuzzy", sólo actúa sobre los mensajes difusos pero ayuda a +encontrarlos y corregirlos uno por uno. + +Hay que tener en cuenta que aunque estas utilidades pueden ser de gran ayuda +para traducir en la linea de comandos, se recomienda el uso de una +herramienta especializada como por ejemplo /{poedit}/. Además, es una buena +idea leer la documentación de debian sobre localizacion (l10n) y, +especificamente para live-manual, las {Directrices para los +traductores}#guidelines-translators. + +*{Nota:}* Se puede utilizar #{make clean}# para limpiar el árbol git antes de enviar los cambios. Este paso no es obligatorio, gracias al fichero .gitignore, pero es una buena práctica para evitar enviar ficheros involuntariamente. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/es/about_project.ssi new file mode 100644 index 0000000..adf1b97 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/about_project.ssi @@ -0,0 +1,111 @@ +:B~ Contribuir al ${project} + +1~about-project Acerca del ${project} + +2~ Motivación + +3~ Desventajas de los sistemas en vivo actuales + +Cuando se comenzó a trabajar en el ${project}, ya existían varios sistemas +en vivo disponibles basados en la distribución Debian y todos hacian un buen +trabajo. Desde la perspectiva de Debian, la mayoría de estos sistemas tenían +alguna de estas desventajas: + +_* No eran proyectos de Debian y por lo tanto no contaban con soporte desde +dentro de Debian. + +_* Mezclaban paquetes de diferentes versiones, por ejemplo *{testing}* y +*{unstable}*. + +_* Solamente soportaban la arquitectura i386. + +_* Modificaban el comportamiento y/o la apariencia de los paquetes, +eliminando contenido para reducirlos de tamaño. + +_* Incluían paquetes de fuera del archivo de Debian. + +_* Utilizaban kernels personalizados con parches que no eran parte de +Debian. + +_* Eran demasiado lentos, debido a su gran tamaño, para ser utilizados como +sistemas de rescate. + +_* No disponían de diferentes medios de instalación, como CDs, DVDs, llaves +USB o imágenes de arranque por red netboot. + +3~ El porqué de crear un sistema en vivo propio. + +Debian es el Sistema Operativo Universal: Debian tiene un sistema en vivo +para mostrar y representar el auténtico y verdadero Debian con las +siguientes ventajas fundamentales: + +_* Es un subproyecto de Debian. + +_* Refleja el estado (actual) de una versión Debian. + +_* Se ejecuta en tantas arquitecturas como es posible. + +_* Consiste solamente de paquetes Debian sin modificar. + +_* No contiene ningún paquete que no forma parte del archivo de Debian. + +_* Utiliza kernels que provienen de Debian inalterados sin parches +adicionales. + +2~ Filosofía + +3~ Solamente paquetes sin modificación alguna de Debian «main» + +Solamente se utilizarán paquetes del repositorio de Debian de la sección +«main». La sección non-free no es parte de Debian y por lo tanto no puede +ser utilizada de ninguna de las maneras para generar imágenes de sistema +oficiales. + +No se modificará ningún paquete. Siempre que se necesite modificar algo, se +hará en coordinación con el correspondiente mantenedor del paquete en +Debian. + +Como excepción, los paquetes del proyecto como son live-boot, live-build o +live-config, pueden ser utilizados temporalmente desde el repositorio del +proyecto, por razones de desarrollo (por ejemplo para crear instantaneas de +pruebas). Estos paquetes serán actualizados en Debian de manera regular. + +3~ Sin configuración especial para el sistema en vivo + +En esta fase, no se creará o instalarán configuraciones alternativas o de +ejemplo. Se utilizarán todos los paquetes con su configuración por defecto, +tal y como quedan después de una instalación normal de Debian. + +Siempre que se necesite una configuración diferente a la de por defecto, se +hará en coodinación con el mantenedor del paquete Debian correspondiente. + +Se puede emplear un sistema para configurar paquetes que utiliza debconf, +permitiendo la personalización de la configuración de los paquetes que van a +ser instalados en la imagen en vivo que se genere, pero las {imágenes en +vivo prefabricadas}#downloading-prebuilt-images solamente utilizarán la +configuración por defecto, a menos que sea absolutamente necesario hacer +cambios para que funcionen en los sistemas en vivo. Siempre que sea posible, +preferimos adaptar los paquetes en el archivo de Debian para que funcionen +mejor en un sistema en vivo en lugar de realizar cambios en nuestra cadena +de herramientas o en {las configuraciones de las imágenes +prefabricadas}#clone-configuration-via-git. Para más información, ver +{Descripción general de la personalización}#customization-overview. + +2~contact Contacto + +_* *{Lista de correo}*: El sistema de contacto principal del proyecto es la +lista de correo en https://lists.debian.org/debian-live/. Se puede enviar un +correo a la lista directamente dirigiéndolo a debian-live@lists.debian.org +Los archivos históricos de la lista están disponibles en +https://lists.debian.org/debian-live/. + +_* *{IRC}*: Un número importante de usuarios y desarrolladores suele estar +presente en el canal #debian-live de irc.debian.org (OFTC). Por favor, se +debe ser paciente cuando se espera una respuesta en el IRC. Si la respuesta +no llega, se puede enviar la pregunta a la lista de correos. + +_* *{BTS}*: El {sistema de gestión de errores de +Debian}https://www.debian.org/Bugs/ (BTS) contiene detalles de problemas +enviados por usuarios y desarrolladores. Los errores están numerados y se +mantiene un registro hasta que son reparados. Si se desea más información +ver {Informes de errores}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/es/appendix_style-guide.ssi new file mode 100644 index 0000000..f4caba7 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/appendix_style-guide.ssi @@ -0,0 +1,379 @@ +:B~ Style guide + +1~style-guide Guía de estilo + +2~ Instrucciones para los autores + +Esta sección se ocupa de algunas consideraciones generales a tener en cuenta +al escribir documentación técnica para live-manual. Se dividen en aspectos +lingüísticos y procedimientos recomendados. + +*{Nota:}* Los autores deberían leer primero {contribuir a este documento}#how-to-contribute + +3~ Aspectos lingüísticos + +_* /{Utilizar un inglés llano}/ + +Tener en cuenta que un alto porcentaje de lectores no son hablantes nativos +de inglés. Así que, como regla general, se debe utilizar frases cortas y +significativas, seguidas de un punto y aparte. + +Esto no significa que se tenga que utilizar un estilo simplista. Es una +sugerencia para tratar de evitar, en la medida de lo posible, las oraciones +subordinadas complejas que hacen que el texto sea difícil de entender para +los hablantes no nativos de inglés. + +_* /{Variedad de inglés}/ + +Las variedades más extendidas del inglés son la británica y la americana, +así que es muy probable que la mayoría de los autores utilicen una u +otra. En un entorno de colaboración, la variedad ideal sería el "inglés +internacional", pero es muy difícil, por no decir imposible, decidir qué +variedad entre todas las existentes, es la mejor. + +Esperamos que las diferentes variedades puedan mezclarse sin crear +malentendidos, pero en términos generales se debe tratar de ser coherente y +antes de decidir sobre el uso de las variantes británica o americana, o +cualquier otro tipo de inglés a su discreción, por favor, dar un vistazo a +cómo escriben otras personas y tratar de imitarlas. + +_* /{Ser equilibrado}/ + +Hay que ser imparcial. Evitar incluir referencias a ideologías totalmente +ajenas a live-manual. La escritura técnica debe ser lo más neutral +posible. Está en la naturaleza misma de la escritura científica. + +_* /{Ser políticamente correcto}/ + +Evitar el lenguaje sexista tanto como sea posible. Si se necesita hacer +referencia a la tercera persona del singular, utilizar preferiblemente +"they" en lugar de "he" o "she" o inventos extraños como "s/he" o "s(he)". + +_* /{Ser concisos}/ + +Ir directamente al grano y no dar vueltas a las cosas. Dar toda la +información necesaria, pero no dar más información de la necesaria, es +decir, no explicar detalles innecesarios. Los lectores son inteligentes. Se +presume algún conocimiento previo de su parte. + +_* /{Minimizar la labor de traducción}/ + +Tener en cuenta que cualquier cosa que se escriba tendrá que ser traducido a +otros idiomas. Esto implica que un número de personas tendrán que hacer un +trabajo extra si se agrega información innecesaria o redundante. + +_* /{Ser coherente}/ + +Como se ha sugerido anteriormente, es casi imposible estandarizar un +documento creado en colaboración en un todo perfectamente unificado. Sin +embargo, se aprecia todo esfuerzo por escribir de manera coherente con el +resto de los autores. + +_* /{Cohesión}/ + +Utilizar conectores de discurso para conseguir un texto coherente y sin +ambigüedades. (Normalmente se llaman connectors). + +_* /{Ser descriptivo}/ + +Es preferible describir el asunto en uno o varios párrafos que la mera +utilización de una serie de oraciones en un típico estilo de +"changelog". Hay que describirlo! Los lectores lo agradecerán. + +_* /{Diccionario}/ + +Buscar el significado de las palabras en un diccionario o una enciclopedia +si no se sabe cómo expresar ciertos conceptos en inglés. Pero hay que tener +en cuenta que un diccionario puede ser el mejor amigo o puede convertirse en +el peor enemigo si no se utiliza correctamente. + +El inglés tiene el mayor vocabulario que existe (con más de un millón de +palabras). Muchas de estas palabras son préstamos de otras lenguas. Al +buscar el significado de las palabras en un diccionario bilingüe la +tendencia de un hablante no nativo de inglés es elegir las que suenan más +similares en su lengua materna. A menudo, esto se convierte en un discurso +excesivamente formal que no suena muy natural en inglés. + +Como regla general, si un concepto se puede expresar utilizando diferentes +sinónimos, es un buen consejo elegir la primera palabra propuesta por el +diccionario. En caso de duda, la elección de palabras de origen germánico +(Normalmente palabras monosílabas) es a menudo lo correcto. Tener en cuenta +que estas dos técnicas puede producir un discurso más bien informal, pero al +menos la elección de palabras será de amplio uso y aceptación general. + +Se recomienda el uso de un diccionario de frases hechas. Son muy útiles +cuando se trata de saber qué palabras suelen aparecer juntas. + +Una vez más, es una buena práctica aprender del trabajo de los otros. El uso +de un motor de búsqueda para comprobar cómo otros autores utilizan ciertas +expresiones puede ayudar mucho. + +_* /{Falsos amigos, modismos y otras expresiones idiomáticas}/ + +Cuidado con los falsos amigos. No importa lo competente que se sea en un +idioma extranjero, se puede caer de vez en cuando en la trampa de los +llamados "falsos amigos", palabras que se parecen en dos idiomas pero cuyos +significados o usos pueden ser completamente diferentes. + +Intentar evitar los modismos tanto como sea posible. Los "modismos" son +expresiones que tienen un significado completamente diferente de lo que sus +palabras parecen decir por separado. A veces, los modismos pueden resultar +difíciles de entender incluso para los hablantes nativos de inglés! + +_* /{Evitar el argot, las abreviaturas, las contracciones...}/ + +A pesar de que se anime a utilizar un inglés sencillo, del día a día, la +escritura técnica pertenece al registro formal de la lengua. + +Intentar evitar el argot, las abreviaturas inusuales que son difíciles de +entender y por encima de todo, las contracciones que tratan de imitar el +lenguaje hablado. Por no hablar de las expresiones familiares o típicas del +irc. + +3~ Procedimientos + +_* /{Probar antes de escribir}/ + +Es importante que los autores prueben sus ejemplos antes de añadirlos a +live-manual para asegurarse de que todo funciona como se describe. Hacer las +pruebas en un entorno chroot limpio o una máquina virtual puede ser un buen +punto de partida. Además, sería ideal si las pruebas fueran llevadas a cabo +en diferentes máquinas con un hardware diferente para detectar los posibles +problemas que puedan surgir. + +_* /{Ejemplos}/ + +Cuando se pone un ejemplo hay que tratar de ser lo más específico +posible. Un ejemplo es, después de todo, tan sólo un ejemplo. + +A menudo es mejor utilizar un ejemplo que sólo se aplica a un caso concreto +que el uso de abstracciones que puedan confundir a los lectores. En este +caso se puede dar una breve explicación de los efectos del ejemplo +propuesto. + +Puede haber algunas excepciones cuando el ejemplo sugiera el uso de comandos +potencialmente peligrosos que, si se utilizan incorrectamente, pueden +provocar la pérdida de datos u otros efectos indeseables similares. En este +caso se debe proporcionar una explicación detallada acerca de los posibles +efectos secundarios. + +_* /{Enlaces externos}/ + +Los enlaces a sitios externos sólo se deben utilizar cuando la información +en esos sitios es crucial para comprender un punto concreto. A pesar de eso, +tratar de utilizar enlaces a sitios externos lo menos posible. Los enlaces +de Internet pueden cambiar de vez en cuando, dando lugar a enlaces rotos y +dejando los argumentos en un estado incompleto. + +Además, las personas que leen el manual sin conexión no tendrán la +oportunidad de seguir los enlaces. + +_* /{Evitar las marcas y las cosas que violan la licencia bajo la que se +publica el manual}/ + +Tratar de evitar las marcas tanto como sea posible. Tener en cuenta que +otros proyectos derivados pueden hacer uso de la documentación que +escribimos. Así que estámos complicando las cosas para ellos si se añade +determinado material específico. + +live-manual se publica bajo la GNU GPL. Esto tiene una serie de +implicaciones que se aplican a la distribución de los materiales (de +cualquier tipo, incluyendo gráficos o logos con derechos de autor) que se +publican en él. + +_* /{Escribir un primer borrador, revisar, editar, mejorar, rehacer de nuevo +si es necesario}/ + + - Lluvia de ideas!. Es necesario organizar las ideas primero en una + secuencia lógica de eventos. + + - Una vez que, de alguna manera, se han organizado esas ideas en la mente, + escribir un primer borrador. + + - Revisar la gramática, la sintaxis y la ortografía. Tener en cuenta que + los nombres propios de las versiones, tales como ${testing} o sid, no se + deben escribir en mayúscula cuando se refieren a los nombres en + clave. Para comprobar la ortografía se puede ejecutar el target + "spell". Es decir, #{make spell}# + + - Mejorar las frases y rehacer cualquier parte si es necesario. + +_* /{Capítulos}/ + +Utilizar el sistema de numeración convencional de los capítulos y +subtítulos. Por ejemplo 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, +2.1 ... y así sucesivamente. Ver marcado a continuación. + +Si es necesario enumerar una serie de pasos o etapas en la descripción, +también se puede utilizar los números ordinales: primero, segundo, tercero +... o en primer lugar, entonces, después, por fin ... Alternativamente, se +pueden utilizar puntos. + +_* /{Marcado}/ + +Y por último, pero no menos importante, live-manual utiliza +{SiSU}http://www.sisudoc.org/ para procesar los ficheros de texto y producir +múltiples formatos. Se recomienda echar un vistazo al {manual de +SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html para +familiarizarme con su marcado, o bien escribir: + +code{ + + $ sisu --help markup + +}code + +Estos son algunos ejemplos de marcado que pueden ser útiles: + + - Para el énfasis/negrita: + +code{ + +*{foo}* o !{foo}! + +}code + +producen: *{foo}* o !{foo}!. Se usan para enfatizar ciertas palabras clave. + + - Para la cursiva: + +code{ + +/{foo}/ + +}code + +produce: /{foo}/. Se usa, por ejemplo, para los nombres de paquetes Debian. + + - Para monospace: + +code{ + +#{foo}# + +}code + +produce: #{foo}#. Se usa, por ejemplo, para los nombres de los comandos. Y +también para resaltar algunas palabras clave o cosas como las rutas. + + - Para los bloques de código: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produce: + +code{ + + $ foo + # bar + +}code + +Se utiliza #{code{}# para abrir y #{}code}# para cerrar los bloques. Es +importante recordar dejar un espacio al principio de cada línea de código. + +2~guidelines-translators Directrices para los traductores + +Esta sección se ocupa de algunas consideraciones generales a tener en cuenta +al traducir el contenido de live-manual. + +Como recomendación general, los traductores deberían haber leído y entendido +las reglas de traducción que se aplican a sus lenguas específicas. Por lo +general, los grupos de traducción y las listas de correo proporcionan +información sobre cómo hacer traducciones que cumplan con los estándares de +calidad de Debian. + +*{Nota:}* Los traductores también deberían leer {Cómo contribuir a este documento}#how-to-contribute. En particular, la sección {Traducción}#translation + +3~ Consejos de traducción + +_* /{Comentarios}/ + +El papel del traductor es transmitir lo más fielmente posible el significado +de las palabras, oraciones, párrafos y textos de como fueron escritos por +los autores originales a su idioma. + +Así que ellos deben abstenerse de añadir comentarios personales o +informaciones adicionales por su cuenta. Si se desea agregar un comentario +para los traductores que trabajan en los mismos documentos, se pueden dejar +en el espacio reservado para ello. Es decir, el encabezado de las cadenas de +los ficheros *{po}* precedidos por el signo *{#}*. La mayoría de los +programas gráficos de traducción pueden manejar ese tipo de comentarios +automáticamente. + +_* /{NT, Nota del Traductor}/ + +Es perfectamente aceptable, sin embargo, incluir una palabra o una expresión +entre paréntesis en el texto traducido si, y sólo si, hace que el +significado de una palabra o expresión difícil sea más clara para el +lector. Dentro de los paréntesis, el traductor debe poner de manifiesto que +la adición es suya utilizando la abreviatura "NT" o "Nota del traductor". + +_* /{Frases impersonales}/ + +Los documentos escritos en Inglés utilizan muchísimo la forma impersonal +"you". En algunos otros idiomas que no comparten esta característica, esto +podría dar la falsa impresión de que los textos originales se dirigen +directamente el lector cuando en realidad no lo hacen. Los traductores deben +ser conscientes de este hecho y reflejarlo en su idioma con la mayor +precisión posible. + +_* /{Falsos amigos}/ + +La trampa de los "falsos amigos" explicada anteriormente se aplica +especialmente a los traductores. Volver a comprobar el significado de los +falsos amigos sospechosos en caso de duda. + +_* /{Marcado}/ + +Los traductores que trabajen inicialmente con los ficheros *{pot}* y +posteriormente con los ficheros *{po}* encontrarán muchas características de +marcado en las cadenas. Se puede traducir el texto, siempre que sea +traducible, pero es extremadamente importante que se utilice exactamente el +mismo marcado que la versión original en inglés. + +_* /{Bloques de código}/ + +A pesar de que los bloques de código son generalmente intraducibles, +incluirlos en la traducción es la única manera de conseguir una traducción +completa al 100%. Y aunque eso signifique más trabajo al principio, ya que +puede ser necesaria la intervención de los traductores cuando hay cambios en +el código, es la mejor manera, a la larga, de identificar lo que se ha +traducido y lo que no al comprobar la integridad de los ficheros .po. + +_* /{Saltos de línea}/ + +Los textos traducidos deben tener exactamente los mismos saltos de línea que +los textos originales. Tener cuidado de presionar la tecla "Enter" o +escribir *{\n}* si aparece en los ficheros originales. Estas nuevas líneas +aparecen a menudo, por ejemplo, en los bloques de código. + +No hay que confundirse, esto no significa que el texto traducido tenga que +tener la misma longitud que la versión en inglés. Eso es prácticamente +imposible. + +_* /{Cadenas intraducibles}/ + +Los traductores nunca deben traducir: + + - Los nombres en clave de las versiones (que debe ser escrito en + minúsculas) + + - Los nombres de los programas + + - Los comandos que se ponen como ejemplos + + - Los metadatos (aparecen a menudo entre dos puntos *{:metadata:}*) + + - Los enlaces + + - Las rutas diff --git a/markup/pod-samples/pod/live-manual/media/text/es/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/es/examples.ssi new file mode 100644 index 0000000..450e5d6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/examples.ssi @@ -0,0 +1,456 @@ +:B~ Ejemplos + +1~examples Ejemplos + +Este capítulo ofrece ejemplos de creación de imágenes de sistemas en vivo +para casos de uso específicos. Si se es nuevo en la creación de una imagen +en vivo propia, se recomienda leer primero los tres tutoriales en secuencia, +ya que cada uno enseña nuevas técnicas que ayudan a utilizar y entender los +ejemplos restantes. + +2~using-the-examples Uso de los ejemplos + +Para poder seguir estos ejemplos es necesario un sistema donde crearlos que +cumpla con los requisitos enumerados en {Requisitos}#requirements y tener +live-build instalado tal y como se describe en {Instalación de +live-build}#installing-live-build. + +Hay que tener en cuenta que, para abreviar, en estos ejemplos no se +especifica una réplica local para la creación de la imagen. Es posible +acelerar las descargas considerablemente si se utiliza una réplica local. Se +puede especificar las opciones cuando se usa #{lb config}#, tal y como se +describe en {Réplicas de Distribution utilizadas durante la +creación}#distribution-mirrors-build-time, o para más comodidad, establecer +el valor por defecto para la creación del sistema en +#{/etc/live/build.conf}#. Basta con crear este fichero y en el mismo, +establecer las variables #{LB_MIRROR_*}# correspondientes a la réplica +preferida. Todas las demás réplicas usadas en el proceso de creación usarán +estos valores por defecto. Por ejemplo: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-updates/" + +}code + +2~tutorial-1 Tutorial 1: Una imagen predeterminada + +*{Caso práctico:}* Crear una primera imagen sencilla, aprendiendo los fundamentos de live-build. + +En este tutorial, vamos a construir una imagen ISO híbrida por defecto que +contenga únicamente los paquetes base (sin Xorg) y algunos paquetes de +soporte, como un primer ejercicio en el uso de live-build. + +No puede ser más fácil que esto: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Si se examina el contenido del directorio #{config/}# se verá almacenada +allí una configuración en esqueleto preparada para ser personalizada o en +este caso para ser usada inmediatamente para construir una imagen por +defecto. + +Ahora, como superusuario, crear la imagen, guardando un log con #{tee}# +mientras se crea. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Suponiendo que todo va bien, después de un rato, el directorio actual +contendrá #{live-image-i386.hybrid.iso}#. Esta imagen ISO híbrida se puede +arrancar directamente en una máquina virtual como se describe en {Probar una +imagen ISO con Qemu}#testing-iso-with-qemu y en {Probar una imagen ISO con +VirtualBox}#testing-iso-with-virtualbox o bien ser copiada a un medio óptico +como un dispositivo USB tal y como se describe en {Grabar una imagen ISO en +un medio físico}#burning-iso-image y {Copiar una imagen ISO híbrida en un +dispositivo USB}#copying-iso-hybrid-to-usb, respectivamente. + +2~tutorial-2 Tutorial 2: Una utilidad de navegador web + +*{Caso práctico:}* Crear una utilidad de navegador web, aprendiendo a aplicar personalizaciones. + +En este tutorial, se creará una imagen adecuada para su uso como utilidad de +navegador web, esto sirve como introducción a la personalización de las +imágenes de sistemas en vivo. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +La elección de LXDE para este ejemplo refleja el deseo de ofrecer un entorno +de escritorio mínimo, ya que el enfoque de la imagen es el uso individual +que se tiene en mente, el navegador web. Se podría ir aún más lejos y +ofrecer una configuración por defecto para el navegador web en +#{config/includes.chroot/etc/iceweasel/profile/}#, o paquetes adicionales de +soporte para la visualización de diversos tipos de contenido web, pero se +deja esto como un ejercicio para el lector. + +Crear la imagen, de nuevo como superusuario, guardando un log como en el +{Tutorial 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +De nuevo, verificar que la imagen está bien y probarla igual que en el +{Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: Una imagen personalizada + +*{Caso práctico:}* Crear un proyecto para conseguir una imagen personalizada, que contenga el software favorito para llevárselo en una memoria USB donde quiera que se vaya, y hacerlo evolucionar en revisiones sucesivas, tal y como vayan cambiando las necesidades y preferencias. + +Como nuestra imagen personalizada irá cambiando durante un número de +revisiones, si se quiere ir siguiendo esos cambios, probar nuevas cosas de +forma experimental y posiblemente volver atrás si no salen bien, se guardará +la configuración en el popular sistema de control de versiones +#{git}#. También se utilizarán las mejores prácticas de configuración +automática a través de scripts #{auto}# como se describe en {Gestionar una +configuración}#managing-a-configuration. + +3~ Primera revisión + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Editar #{auto/config}# del siguiente modo: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Ejecutar #{lb config}# para generar el árbol de configuración, utilizando el +script #{auto/config}# que justo se acaba de crear: + +code{ + + $ lb config + +}code + +Completar la lista de paquetes local: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +En primer lugar con #{--architectures i386}# se asegura de que en un sistema +de creación #{amd64}# se crea una versión de 32-bits adecuada para ser usada +en la mayoría de máquinas. En segundo lugar, se usa #{--linux-flavours +686-pae}# porque no se espera usar esta imagen en sistemas mucho más +viejos. En tercer lugar se elige el metapaquete /{lxde}/ para proporcionar +un escritorio mínimo. Y, por último, se añaden dos paquetes iniciales +favoritos: /{iceweasel}/ y /{xchat}/. + +Ahora, crear la imagen: + +code{ + + # lb build + +}code + +Tener en cuenta que a diferencia de los dos primeros tutoriales, ya no se +tiene que escribir #{2>&1 | tee build.log}# ya que esto se incluye ahora en +#{auto/build}#. + +Una vez que se ha probado la imagen (como en el {Tutorial 1}#tutorial-1) y +se ha asegurado de que funciona, es el momento de iniciar el repositorio +git, añadiendo sólo los scripts auto que se acaba de crear, y luego hacer el +primer commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Segunda revisión + +En esta revisión, vamos a limpiar desde la primera creación, agregar el +paquete /{vlc}/ a nuestra configuración, crear de nuevo, probar y enviar los +cambios al git. + +El comando #{lb clean}# limpiará todos los ficheros generados en las +primeras creaciones a excepción del caché, lo cual ahorra tener que volver a +descargar de nuevo los paquetes. Esto asegura que el siguiente #{lb build}# +vuelva a ejecutar todas las fases para regenerar los ficheros de nuestra +nueva configuración. + +code{ + + # lb clean + +}code + +Añadir ahora el paquete /{vlc}/ a nuestra lista de paquetes local en +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Crear de nuevo: + +code{ + +# lb build + +}code + +Probar, y cuando se esté satisfecho, enviar la próxima revisión al git: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Por supuesto, es posible hacer cambios más complicados en la configuración, +tal vez añadiendo ficheros en los subdirectorios de #{config/}#. Cuando se +envian nuevas revisiones, hay que tener cuidado de no editar a mano o enviar +los ficheros del nivel superior en #{config}# que contienen variables +#{LB_*}# ya que estos son productos de creación también y son siempre +limpiados por #{lb clean}# y recreados con #{lb config}# a través de sus +respectivos scripts #{auto}#. + +Hemos llegado al final de nuestra serie de tutoriales. Si bien son posibles +muchos más tipos de personalización, aunque sólo sea con las pocas +características explicadas en estos sencillos ejemplos, se puede crear una +variedad casi infinita de imágenes diferentes. Los ejemplos que quedan en +esta sección abarcan varios casos de usos diferentes procedentes de las +experiencias recogidas de los usuarios de sistemas en vivo. + +2~ Un cliente VNC kiosk + +*{Caso Práctico:}* Crear una imagen con live-build para que se conecte directamente a un servidor VNC al arrancar. + +Crear un directorio de construcción y lanzar una configuración de esqueleto +en su interior, desactivando «recommends» para conseguir un sistema +mínimo. Y a continuación, crear dos listas iniciales de paquetes: La primera +generada con un script proporcionado por live-build llamado #{Packages}# +(ver {Generar listas de paquetes}#generated-package-lists), y la segunda +lista una que incluya /{xorg}/, /{gdm3}/, /{metacity}/ y /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +Como se explica en {Ajuste de APT para ahorrar +espacio}#tweaking-apt-to-save-space puede ser necesario volver a agregar +algunos paquetes recomendados para que la imagen funcione correctamente. + +Una manera fácil de conocer todos los «recommends» es utilizar +/{apt-cache}/. Por ejemplo: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +En este ejemplo, descubrimos que teníamos que volver a incluir varios +paquetes recomendados por live-config y live-boot: #{user-setup}# para hacer +funcionar el inicio automático de sesión y #{sudo}# programa esencial para +apagar el sistema. Además, podría ser útil añadir #{live-tools}# para poder +copiar la imagen en la memoria RAM y #{eject}# para finalmente poder +expulsar el medio en vivo. Por eso: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +Después, crear el directorio #{/etc/skel}# en #{config/includes.chroot}# y +poner dentro un fichero #{.xsession}# personalizado para el usuario que por +defecto ejecutará /{metacity}/ e iniciará el /{xvncviewer}/, conectándo al +puerto #{5901}# de un servidor en #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Crear la imagen: + +code{ + + # lb build + +}code + +Disfrutarlo. + +2~ Una imagen básica para un pendrive USB de 128MB + +*{Caso Práctico:}* Crear una imagen quitando algunos componentes para que quepa en un pendrive USB de 128MB dejándo un poco de espacio libre para poder usarlo para lo que se quiera. + +Al optimizar una imagen para adaptarla al tamaño de algunos medios de +almacenamiento, es necesario comprender el equilibrio que se está haciendo +entre tamaño y funcionalidad. En este ejemplo, se recorta tanto sólo para +dar cabida a material adicional dentro de un tamaño de 128MB, pero sin hacer +nada para destruir la integridad de los paquetes que contiene, tales como la +depuración de las variantes locales a través del paquete /{localepurge}/ u +otro tipo de optimizaciones «intrusivas». Cabe destacar que se utiliza +#{--debootstrap-options}# para crear un sistema mínimo desde el principio. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +Para hacer que la imagen funcione correctamente, tenemos que volver a +añadir, al menos, dos paquetes recomendados, que son excluidos por la opción +#{--apt-recommends false}#. Ver {Ajuste de APT para ahorrar +espacio}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Ahora, crear la imagen de forma habitual: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +En el sistema del autor, en el momento de escribir esto, la configuración +anterior produjo una imagen de 110MB. Esto se compara favorablemente en +tamaño con la imagen de 192MB producida por la configuración por defecto en +el {Tutorial 1}#tutorial-1. + +Dejar fuera los índices de APT con #{--apt-indices false}# ahorra una +cantidad importante de espacio, la desventaja es que será necesario hacer un +#{apt-get update}# antes de usar apt en el sistema en vivo. Excluyendo los +paquetes recomendados con #{--apt-recommends false}# se ahorra un poco de +espacio adicional a costa de omitir algunos paquetes que de otro modo podría +esperarse que estuvieran alli. #{--debootstrap-options "--variant=minbase"}# +preinstala un sistema mínimo desde el principio. El hecho de no incluir +automáticamente paquetes de firmware con #{--firmware-chroot false}# también +ahorra un poco de espacio. Y por último, #{--memtest none}# evita la +instalación de un comprobador de memoria. + +*{Nota:}* También se puede conseguir un sistema mínimo utilizando scripts gancho como por ejemplo el script #{stripped.hook.chroot}# que se encuentra en #{/usr/share/doc/live-build/examples/hooks}#, que puede reducir aún más el tamaño de la imagen hasta 91MB. Sin embargo, el script elimina documentación y otros ficheros de los paquetes instalados en el sistema. Esto viola la integridad de los paquetes y como se comenta en el encabezado del script, puede tener consecuencias imprevistas. Es por eso por lo que el uso de /{debootstrap}/ es el método recomendado para conseguir este objetivo. + +2~ Un escritorio GNOME con variante local e instalador + +*{Caso práctico:}* Crear una imagen que contenga el escritorio gráfico GNOME, la variante local Suiza y un instalador. + +Se desea crear una imagen iso-hybrid para la arquitectura i386 con un +escritorio preferido, en este caso el GNOME, que contiene todos los mismos +paquetes que serían instalados por el programa de instalación estándar de +Debian para GNOME. + +El primer problema es descubrir los nombres de las tareas adecuadas. En la +actualidad, live-build no puede ayudar en esto. Aunque podríamos tener +suerte y encontrarlos a base de pruebas, hay una herramienta, +#{grep-dctrl}#, para extraerlos de las descripciones de tareas en +tasksel-data, para proceder, asegurarse de tener ambas cosas: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Ahora podemos buscar las tareas apropiadas, primero con: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +Con este comando, se descubre que la tarea se llama, sencillamente, +german. Ahora, para encontrar las tareas relacionas: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +En el momento del arranque se va a generar la variante local *{de_CH.UTF-8}* +y seleccionar la distribución del teclado *{ch}*. Ahora vamos a poner las +piezas juntas. Recordando de {Utilizar metapaquetes}#using-metapackages que +los metapaquetes tienen el prefijo #{task-}#, especificamos estos parámetros +del lenguaje en el arranque y a continuación añadimos los paquetes de +prioridad estándar y los metapaquetes que hemos descubierto a la lista de +paquetes de la siguiente manera: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Tener en cuenta que se ha incluido el paquete /{debian-installer-launcher}/ +para lanzar el instalador desde el escritorio en vivo. El kernel #{586}#, +necesario para que el lanzador funcione correctamente, se incluye por +defecto. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/es/live-manual.ssm new file mode 100644 index 0000000..9c7b996 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manual de Live Systems" + +creator: + author: "Proyecto Live Systems <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "Este programa es software libre: puede ser redistribuido y/o modificado bajo los términos de la GNU General Public License publicada por la Free Software Foundation, bien de la versión 3 de la Licencia, o (a su elección) cualquier versión posterior. \\ \\ Este programa se distribuye con la esperanza de que sea útil, pero SIN NINGUNA GARANTÍA, incluso sin la garantía implícita de COMERCIALIZACIÓN o IDONEIDAD PARA UN PROPÓSITO PARTICULAR. Consulte la GNU General Public License para más detalles. \\ \\ Debería haber recibido una copia de la General Public License GNU junto con este programa. Si no, vea http://www.gnu.org/licenses/. \\ \\ El texto completo de la GNU Licencia Pública General se pueden encontrar en /usr/share/common-licenses/GPL-3" + +date: + published: "2015-08-23" + +publisher: "Live Systems Project <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ Acerca de este manual + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Usuario + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Proyecto + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Ejemplos + +<< examples.ssi + +:B~ Apéndice + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/es/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/es/project_bugs.ssi new file mode 100644 index 0000000..b3ceb93 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/project_bugs.ssi @@ -0,0 +1,221 @@ +:B~ Cómo informar acerca de errores. + +1~bugs Informes de errores. + +Los sistemas en vivo están lejos de ser perfectos, pero queremos que sean lo +más perfectos posible - con su ayuda. No dudar en informar de un error. Es +mejor llenar un informe dos veces que no hacerlo nunca. Sin embargo, este +capítulo incluye recomendaciones sobre cómo presentar buenos informes de +errores. + +Para los impacientes: + +_* Primero, siempre se debe comprobar el estado actualizado de la imagen en +busca de problemas conocidos en la página web http://live-systems.org/. + +_* Antes de presentar un informe de errores, se debe intentar reproducir el +error con las *{versiones más recientes}* de live-build, live-boot, +live-config y live-tools de la rama de que se está utilizando (como la +última versión 4.x de live-build si se utiliza live-build 4). + +_* Se debe intentar proporcionar *{una información tan específica como sea +posible}* acerca del error. Esto incluye (al menos) la versión de +live-build, live-boot, live-config y live-tools utilizada y la distribución +del sistema en vivo que se está construyendo. + +2~ Problemas conocidos + +Debido a que Debian *{testing}* y Debian *{unstable}* están cambiando +continuamente, no siempre es posible crear un sistema con éxito cuando se +especifica cualquiera de estas dos versiones como distribución objetivo. + +% FIXME: + +Si esto causa mucha dificultad, no se debe crear un sistema basado en +*{testing}* o *{unstable}*, sino que debe utilizarse *{stable}*. live-build +siempre crea, por defecto, la versión *{stable}* . + +Los problemas detectados se especifican en la sección 'status' de la página +web http://live-systems.org/. + +Está fuera del alcance de este manual enseñar cómo identificar y solucionar +correctamente problemas de los paquetes de las distribuciones en desarrollo, +sin embargo, hay dos cosas que siempre se puede intentar: Si se detecta un +error de creación cuando la distribución de destino es *{testing}*, se debe +intentar con *{unstable}*. Si *{unstable}* no funciona bien, se debe volver +a *{testing}* haciendo un pin con la nueva versión del paquete de +*{unstable}* (véase {APT pinning}#apt-pinning para más detalles). + +2~ Reconstruir desde cero + +Para asegurarse de que un error en particular no es causado por crear el +sistema basándose en los datos de un sistema anterior, se debe reconstruir +el sistema en vivo entero, desde el principio y comprobar si el error es +reproducible. + +2~ Utilizar paquetes actualizados + +Utilizar paquetes obsoletos puede causar problemas importantes al tratar de +reproducir (y en última instancia, solucionar) el problema. Hay que +asegurarse de que el sistema de construcción está actualizado y cualquier +paquete que se incluya en la imagen esté también al día . + +2~collect-information Recopilar información + +Se debe proporcionar información suficiente con el informe. Como mínimo, la +versión exacta de live-build donde se encuentra el error y los pasos para +reproducirlo. Se debe utilizar el sentido común e incluir cualquier +información pertinente si se cree que podría ayudar a resolver el problema. + +Para sacar el máximo provecho de un informe de errores, se requerirá al +menos la siguiente información: + +_* Arquitectura del sistema anfitrión + +_* Distribución del sistema anfitrión. + +_* La versión de live-build del sistema anfitrión. + +_* Versión de /{debootstrap}/ en el sistema anfitrión. + +_* Arquitectura del sistema en vivo. + +_* Distribución del sistema en vivo. + +_* Versión de live-boot en el sistema en vivo. + +_* Versión de live-config en el sistema en vivo. + +_* Versión de live-tools en el sistema en vivo. + +Se puede generar un log del proceso de creación mediante el comando +#{tee}#. Se recomienda hacer esto de forma automática con un script +#{auto/build}# (ver {Gestionar una configuración}#managing-a-configuration +para más detalles). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +En el momento del arranque, live-boot y live-config guardan sus logs en +#{/var/log/live/}#. Comprobar si hay algún mensaje de error en estos +ficheros. + +Además, para descartar otros errores, siempre es una buena idea comprimir en +un .tar el directorio #{config/}# y subirlo a algún lugar, para que el +equipo de Debian Live pueda reproducir el error (*{No}* se debe enviar como +documento adjunto a la lista de correo). Si esto es difícil (por ejemplo, +debido a su tamaño) se puede utilizar la salida del comando #{lb config +--dump}# que produce un resumen del árbol de configuración (es decir, listas +de archivos de los subdirectorios de #{config /}# pero no los incluye). + +Hay que recordar que los informes a enviar se deben hacer en ingles, por lo +que para generar los logs en este idioma se debe utilizar la variante local +English, p.ej. ejecutar los comandos de live-build o cualquier otro +precedidos de #{LC_ALL=C}# o #{LC_ALL=en_US}#. + +2~ Aislar el fallo si es posible + +Si es posible, aislar el caso del fallo al menor cambio posible que lo +produzca. No siempre es fácil hacer esto, así que si no se consigue para el +informe, no hay que preocuparse. Sin embargo, si se planea el ciclo de +desarrollo bién, con conjuntos de cambios lo bastante pequeños por +iteración, puede ser posible aislar el problema mediante la construcción de +una simple «base» de configuración que se ajuste a la configuración actual +deseada, más el conjunto del cambio que falla añadido. Si resulta difícil +determinar que cambios produjeron el error, puede ser que se haya incluido +demasiado en cada conjunto de cambios y se deba desarrollar en incrementos +más pequeños. + +2~ Utilizar el paquete correcto sobre el que informar del error + +Si no se sabe qué componente es responsable del error o si el error es un +error general relativo a los sistemas en vivo, se puede rellenar un informe +de errores contra el pseudo-paquete debian-live. + +Sin embargo, se agradece si se intenta limitar la búsqueda a donde aparece +el error. + +3~ En la preinstalación (bootstrap) en tiempo de creación. + +live-build crea primero un sistema Debian básico con /{debootstrap}/. Si un +error aparece en este momento, se debe comprobar si está relacionado con un +paquete específico de Debian (es lo más probable), o si está relacionado con +la herramienta de preinstalación en sí. + +En ambos casos, esto no es un error en el sistema en vivo, sino de Debian en +sí mismo, por lo cual nosotros probablemente no podamos solucionarlo +directamente. Informar del error sobre la herramienta de preinstalación o el +paquete que falla. + +3~ Mientras se instalan paquetes en tiempo de creación. + +live-build instala paquetes adicionales del archivo de Debian que pueden +fallar en función de la distribución Debian utilizada y del estado diario +del archivo Debian. Se debe comprobar si el error es reproducible en un +sistema Debian normal, si el fallo aparece en esta etapa. + +Si este es el caso, esto no es un error en el sistema en vivo, sino de +Debian - se debe informar sobre el paquete que falla. Se puede obtener más +información ejecutando /{debootstrap}/ de forma separada del sistema de +creación en vivo o ejecutando #{lb bootstrap --debug}#. + +Además, si se está utilizando una réplica local y/o cualquier tipo de proxy +y se experimenta un problema, se debe intentar reproducir siempre +preinstalando desde una réplica oficial. + +3~ En tiempo de arranque + +Si la imagen no arranca, se debería informar a la lista de correo, junto con +la información solicitada en {Recopilar información}#collect-information. No +hay que olvidar mencionar, cómo y cuándo la imagen falla, si es utilizando +virtualización o hardware real. Si se está utilizando una tecnología de +virtualización de cualquier tipo, se debe probar la imagen en hardware real +antes de informar de un error. Proporcionar una captura de pantalla del +error también es muy útil. + +3~ En tiempo de ejecución + +Si un paquete se ha instalado correctamente, pero falla cuando se ejecuta el +sistema en vivo, esto es probablemente un error en el sistema en vivo. Sin +embargo: + +2~ Hacer la investigación + +Antes de presentar el informe de errores, buscar en la web el mensaje de +error en particular o el síntoma que se está percibiendo. Como es muy poco +probable que sea la única persona que tiene ese problema en concreto, +siempre existe la posibilidad de que se haya discutido en otras partes y +exista una posible solución, parche o se haya propuesto una alternativa. + +Se debe prestar especial atención a la lista de correo del sistema en vivo, +así como a su página web, ya que seguramente tienen la información más +actualizada. Si esa información existe, se debe incluir una referencia a +ella en el informe de errores. + +Además, se debe comprobar las listas de errores actuales de live-build, +live-boot, live-config y live-tools y verificar si se ha informado ya de +algo similar. + +2~ Dónde informar de los fallos + +El ${project} realiza un seguimiento de todos los errores en el sistema de +seguimiento de errores de Debian (BTS). Para obtener información sobre cómo +utilizar el sistema, consultar https://bugs.debian.org/. También se puede +enviar los errores mediante el comando #{reportbug}# del paquete con el +mismo nombre. + +En general, se debe informar sobre los errores en tiempo de creación contra +el paquete live-build. De los fallos en tiempo de arranque contra el paquete +live-boot, y de los errores en tiempo de ejecución contra el paquete +live-config. Si no se está seguro de qué paquete es el adecuado o se +necesita más ayuda antes de presentar un informe de errores, lo mejor es +enviar un informe contra el pseudo-paquete debian-live. Nosotros nos +encargaremos de reasignarlo donde sea apropiado. + +Hay que tener en cuenta que los errores que se encuentran en las +distribuciones derivadas de Debian (como Ubuntu y otras) *{no}* deben +enviarse al BTS de Debian a menos que también se puedan reproducir en un +sistema Debian usando paquetes oficiales de Debian. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/es/project_coding-style.ssi new file mode 100644 index 0000000..8950bdb --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/project_coding-style.ssi @@ -0,0 +1,155 @@ +:B~ Estilo de código + +1~coding-style Estilo de código + +En este capítulo se documenta el estilo de código utilizado en los sistemas +en vivo. + +2~ Compatibilidad + +_* No utilizar sintaxis o semántica que sea única para el intérprete de +comandos Bash. Por ejemplo, el uso de arrays. + +_* Utilizar únicamente el subconjunto POSIX - por ejemplo, usar $(foo) en +lugar de `foo`. + +_* Se puede comprobar las secuencias de comandos con 'sh -n' y +'checkbashisms'. + +_* Asegurarse de que el código funcione con 'set -e'. + +2~ Sangrado + +_* Utilizar siempre los tabuladores en lugar de espacios. + +2~ Ajuste de líneas + +_* En general, las líneas contienen 80 caracteres como máximo. + +_* Utilizar los saltos de línea al «estilo Linux»: + +Mal: + +code{ + + if foo; then + bar + fi + +}code + +Bien: + +code{ + + if foo + then + bar + fi + +}code + +_* Lo mismo vale para las funciones: + +Mal: + +code{ + + Foo () { + bar + } + +}code + +Bien: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Las variables deben escribirse siempre en letras mayúsculas. + +_* Las variables que se utiliza en live-build siempre comienzan con el +prefijo #{LB_}# + +_* Las variables temporales internas de live-build deben comenzar con el +prefijo #{\_LB_}# + +_* Las variables locales comienzan con el prefijo live-build #{\_\_LB_}# + +_* Las variables en relación a un parámetro de arranque en live-config +comienzan con #{LIVE_}#. + +_* Todas las demás variables de live-config comienzan con el prefijo #{_}# + +_* Utilizar llaves para las variables, por ejemplo, escribir #{${FOO}}# en +lugar de #{$FOO}#. + +_* Utilizar comillas dobles en las variables para evitar dejar espacios en +blanco: Escribir #{"${FOO}"}# en lugar de #{${FOO}}#. + +_* Por motivos de coherencia, se debe utilizar siempre comillas en la +asignación de valores a las variables: + +Mal: + +code{ + + FOO=bar + +}code + +Bien: + +code{ + + FOO="bar" + +}code + +_* Si se utilizan múltiples variables, incluir la expresión completa entre +comillas dobles: + +Mal: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Bien: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscelánea + +_* Se debe utilizar "#{|}#" (sin comillas) como separador cuando se invoque +a sed, p.ej. "#{sed -e 's|foo|bar|'}#" (Pero sin las comillas "") + +_* No se debe utilizar el comando #{test}# para hacer comparaciones o +pruebas, usar "#{[}#" "#{]}#" (sin ""); p.ej. "#{if [ -x /bin/foo ]; ...}#" +en lugar de "#{if test -x /bin/foo; ...}#". + +_* Se debe utilizar #{case}# siempre que sea posible en lugar de #{test}#, +ya que es más fácil de leer y más rápido en la ejecución. + +_* Usar mayúsculas en los nombres de las funciones para evitar confusiones +con el entorno de los usuarios. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/es/project_contributing.ssi new file mode 100644 index 0000000..b462fc8 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/project_contributing.ssi @@ -0,0 +1,120 @@ +:B~ Contribuir al proyecto + +1~contributing-to-project Contribuir al proyecto + +Cuando se envía una contribución se debe identificar claramente al titular +de los derechos de autor e incluir la declaración de las licencias +aplicables. Se hace notar que para ser aceptada, una contribución debe ser +publicada bajo la misma licencia que el resto del documento, es decir, GPL +versión 3 o posterior. + +Las contribuciones al proyecto, tales como traducciones y parches, son muy +bienvenidas. Cualquiera puede hacer una entrega en los repositorios, sin +embargo, a la hora de hacer grandes cambios, es conveniente enviarlos a la +lista de correo para debatirlos primero. Ver la sección {Contacto}#contact +para más información. + +El ${project} utiliza Git como sistema de control de versiones y gestión de +código fuente. Como se explica en {Repositorios Git}#git-repositories hay +dos ramas principales de desarrollo: *{debian}* y *{debian-next}*. Todo el +mundo puede hacer entregas a las ramas debian-next de los repositorios +live-boot, live-build, live-config, live-images, live-manual y live-tools. + +Sin embargo, existen ciertas restricciones. El servidor rechazará: + +_* Entregas que no sean fast-forward + +_* Entregas que hagan fusiones. + +_* Añadir o borrar etiquetas o ramas. + +A pesar de que todas las entregas pueden ser revisadas, pedimos usar el +sentido común y hacer buenos commits con mensajes de commit adecuados. + +_* Hay que escribir mensajes de entrega que consistan en una frase en ingles +con significado completo, comenzando con una letra mayúscula y acabando con +un punto final. Es habitual comenzar estas frases con la forma +'Fixing/Adding/Removing/Correcting/Translating/...'. + +_* Escribir buenos mensajes de entrega. La primera frase debe ser un resumen +exacto de los contenidos del commit, que se incluirá en la lista de +cambios. Si se necesita hacer algunas aclaraciones, escribirlas debajo +dejando una línea en blanco después de la primera y luego otra línea en +blanco después de cada párrafo. Las líneas de los párrafos no deben superar +los 80 caracteres de longitud. + +_* Hacer entregas de forma atómica, es decir, no mezclar cosas no +relacionadas en el mismo commit. Hacer un commit diferente para cada cambio +que se realice. + +2~ Realizar cambios + +Para hacer una entrega a los repositorios, se debe seguir el siguiente +procedimiento. Aquí se utiliza live-manual como ejemplo, por eso hay que +sustituirlo por el nombre del repositorio con el que se desea trabajar. Para +obtener información detallada sobre cómo editar live-manual ver {Contribuir +a este documento}#how-to-contribute. + +_* Obtener la clave pública de entrega: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Añadir la siguiente sección en el fichero de configuración de +openssh-client: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Obtener un clon del manual mediante git utilizando ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Acordarse de configurar el autor y el email en Git: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Importante:}* Recordar que hay que enviar los cambios a la rama *{debian-next}*. + +_* Efectuar los cambios. En este ejemplo, primero se escribiría una nueva +sección sobre cómo aplicar parches y luego se añadirían los ficheros y se +escribiría el mensaje de la siguiente manera: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Para finalizar se realizará la entrega al servidor: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/es/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/es/project_git.ssi new file mode 100644 index 0000000..be125c6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/project_git.ssi @@ -0,0 +1,87 @@ +:B~ Repositorios Git + +1~git-repositories Repositorios Git + +La lista de todos los repositorios disponibles del ${project} está en +http://live-systems.org/gitweb/. Las URLs git del proyecto tienen la forma: +#{protocolo://live-systems.org/git/repositorio}#. Por lo tanto, para clonar +live-manual en sólo lectura, lanzar: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +O, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +O, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +Las direcciones para clonar con permiso de escritura tienen la forma: +#{git@live-systems.org:/repositorio}#. + +Así que, de nuevo, para clonar live-manual a través de ssh escribir: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +El árbol git se compone de varias ramas diferentes. Las ramas *{debian}* y +*{debian-next}* son particularmente notables porque contienen el trabajo +real que, con el tiempo, será incluido en cada nueva versión. + +Después de clonar cualquiera de los repositorios existentes, nos encontramos +en la rama *{debian}*. Esto es apropiado para echar un vistazo al estado de +la última versión del proyecto, pero antes de empezar a trabajar es +fundamental cambiar a la rama *{debian-next}*. Para ello: + +code{ + + $ git checkout debian-next + +}code + +La rama *{debian-next}*, la cual no es siempre fast-forward, es donde se +realizan todos los cambios antes de que se fusionen en la rama +*{debian}*. Para hacer una analogía, es como un campo de pruebas. Si se está +trabajando en esta rama y se necesita hacer un pull, se tendrá que hacer un +#{git pull --rebase}# para que las modificaciones locales se guarden +mientras se actualiza desde el servidor y entonces los cambios locales se +pondrán encima de todos los demás. + +2~ Manejo de múltiples repositorios + +Si se tiene la intención de clonar varios de los repositorios y cambiar a la +rama *{debian-next}* de inmediato para comprobar el último código, escribir +un parche o contribuir con una traducción se debe saber que el servidor +proporciona un fichero #{mrconfig}# para facilitar el manejo de múltiples +repositorios. Para utilizarlo es necesario instalar el paquete /{mr}/ y a +continuación, lanzar: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +Este comando automáticamente clonará y cambiará a la rama *{debian-next}* +los repositorios de desarrollo de los paquetes Debian producidos por el +proyecto. Estos incluyen, entre otros, el repositorio live-images, que +contiene las configuraciones utilizadas para las imágenes prefabricadas que +el proyecto publica para uso general. Para obtener más información sobre +cómo utilizar este repositorio, consultar {Clonar una configuración +publicada a través de Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/es/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/es/project_procedures.ssi new file mode 100644 index 0000000..0bf0e8b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/project_procedures.ssi @@ -0,0 +1,103 @@ +:B~ Procedimientos + +1~procedures Procedimientos + +Este capítulo documenta los procedimientos dentro del ${project} para +diversas tareas que requieren la cooperación con otros equipos de Debian. + +2~ Principales lanzamientos + +El lanzamiento de una nueva versión estable de Debian involucra a una gran +cantidad de equipos diferentes que trabajan juntos para conseguirlo. En un +momento dado, el equipo Live aparece y desarrolla imágenes en vivo del +sistema. Los requisitos para ello son: + +_* Una réplica de las versiones publicadas de los archivos de debian y +debian-security a la que pueda acceder el buildd de debian-live. + +_* Es necesario conocer el nombre de la imagen +(p.ej. debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* Es necesario sincronizar los datos de debian-cd (lista de exclusión de +udeb) + +_* Las imágenes se crean y se almacenan en cdimage.debian.org. + +2~ Nuevas versiones + +_* Una vez más, se necesita una réplica actualizada de Debian y +debian-security. + +_* Las imágenes se crean y se almacenan en cdimage.debian.org. + +_* Correo para enviar notificaciones. + +3~ Última actualización de una versión Debian + +Recordar que se deben ajustar tanto las réplicas de chroot como las de +binary cuando se construye la última serie de imágenes para una versión de +Debian después de haber sido trasladada de ftp.debian.org a +archive.debian.org. De esta manera, las viejas imágenes prefabricadas siguen +siendo útiles, sin modificaciones de los usuarios. + +3~ Plantilla para anunciar nuevas versiones. + +Se puede generar un anuncio de nuevas versiones usando la siguiente +plantilla y el siguiente comando: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Revisar el mensaje de correo con cuidado antes de enviarlo a otras personas +para su corrección. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_basics.ssi new file mode 100644 index 0000000..266933c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_basics.ssi @@ -0,0 +1,676 @@ +:B~ Conceptos básicos + +1~the-basics Conceptos básicos + +Este capítulo contiene una breve descripción del proceso de creación de las +imágenes en vivo y las instrucciones para el uso de los tres tipos de +imágenes más utilizadas. El tipo de imagen más versátil, #{iso-hybrid}#, se +puede utilizar en una máquina virtual, en medios ópticos u otros +dispositivos de almacenamiento USB. En ciertos casos especiales, como se +explica más adelante, las imágenes #{hdd}#, pueden ser las más adecuadas. El +capítulo incluye instrucciones detalladas para crear y utilizar una imagen +de tipo #{netboot}#, que es un poco más complicado debido a la configuración +necesaria en el servidor. Es un tema ligeramente avanzado para cualquier +persona que no esté familiarizada con el arranque en red, pero se incluye +aquí porque una vez que se realiza toda la configuración, es una forma muy +conveniente para probar y desplegar imágenes de arranque en red local sin la +molestia de tratar con los dispositivos de almacenamiento de la imagen. + +La sección termina con una rápida introducción al {arranque desde +internet}#webbooting, que es, quizás, la manera más rápida de utilizar +diferentes imágenes para diferentes propósitos, cambiando de una a otra +según las necesidades, utilizando internet como medio. + +A lo largo de todo el capítulo se hace a menudo referencia al nombre de las +imágenes producidas por defecto por live-build. Si se {descarga una imagen +ya creada}#downloading-prebuilt-images el nombre puede variar. + +2~what-is-live ¿Qué es un sistema en vivo? + +Por lo general, un sistema en vivo se refiere a un sistema operativo que +arranca en un equipo desde un medio extraíble, como un CD-ROM, dispositivo +USB, o desde una red, listo para usar sin ningún tipo de instalación en la +unidad de costumbre, con configuración automática en tiempo de ejecución +(Ver {Términos}#terms). + +Con los sistemas en vivo, es un sistema operativo, creado para una de las +arquitecturas soportadas (actualmente amd64 y i386). Se compone de las +siguientes partes: + +_* *{Imágen del kernel de Linux}*, normalmente llamada #{vmlinuz*}# + +_* *{Imagen del Disco RAM inicial (initrd)}*: Un Disco RAM configurado para +el arranque de Linux, que incluya los módulos posiblemente necesarios para +montar la imagen del sistema y algunos scripts para ponerlo en marcha. + +_* *{Imagen del sistema}*: La imagen del sistema de ficheros raíz. Por lo +general, se utiliza un sistema de ficheros comprimido SquashFS para reducir +al mínimo el tamaño de la imagen en vivo. Hay que tener en cuenta que es de +sólo lectura. Por lo tanto, durante el arranque del sistema en vivo se +utiliza un disco RAM y un mecanismo de «unión» que permite escribir ficheros +en el sistema en funcionamiento. Sin embargo, todas las modificaciones se +perderán al apagar el equipo a menos que se use de modo opcional la +persistencia (ver {Persistencia}#persistence). + +_* *{Gestor de arranque}*: Una pequeña pieza de código diseñada para +arrancar desde el medio de almacenamiento escogido, posiblemente mostrando +un menú o un indicador de arranque para permitir la selección de +opciones/configuración. Carga el kernel de Linux y su initrd para funcionar +con un sistema de ficheros asociado. Se pueden usar soluciones diferentes, +dependiendo del medio de almacenamiento de destino y el formato del sistema +de ficheros que contenga los componentes mencionados anteriormente: isolinux +para arrancar desde un CD o DVD en formato ISO9660, syslinux para arrancar +desde el disco duro o unidad USB desde una partición VFAT, extlinux para +formatos ext2/3/4 y particiones btrfs, pxelinux para arranque de red PXE, +GRUB para particiones ext2/3/4 , etc. + +Se puede utilizar live-build para crear la imagen del sistema a partir de +ciertas especificaciones, incluir un kernel de Linux, su initrd y un gestor +de arranque para ponerlos en funcionamiento, todo ello en un formato que +depende del medio de almacenamiento elegido (imagen ISO9660, imagen de +disco, etc.) + +2~downloading-prebuilt-images Descarga de imágenes prefabricadas + +Si bien el objetivo de este manual es el desarrollo y la construcción de +imágenes en vivo propias, puede que simplemente se desee probar una de +nuestras imágenes prefabricadas, ya sea como una iniciación a su uso o como +paso previo a la construcción de imágenes personalizadas. Estas imágenes +están construidas utilizando nuestro {repositorio git +live-images}#clone-configuration-via-git y las versiones estables oficiales +se publican en https://www.debian.org/CD/live/. Además, las versiones +antiguas y las futuras, así como las imágenes no oficiales que contienen +firmware y drivers no libres están disponibles en +http://live-systems.org/cdimage/release/. + +2~using-iso-hybrid Uso del servicio de creación de imágenes web + +Como un servicio a la comunidad, se ofrece una interfaz web de construcción +de imágenes en vivo en http://live-systems.org/build/. Este sitio se +mantiene en base al mejor esfuerzo. Es decir, aunque nos esforzamos por +mantenerlo al día y de que esté operativo en todo momento, así como de +emitir anuncios de interrupciones importantes en el servicio, no podemos +garantizar un 100% de disponibilidad o una creación de imágenes rápida, y el +servicio de vez en cuando puede tener problemas que tarden algún tiempo en +resolverse. Si se tiene problemas o preguntas acerca de este servicio, +ponerse {en contacto}#contact con nosotros, proporcionando el enlace a la +página dónde se recoge la información pertinente a la imagen. + +3~ Uso y advertencias del servicio de creación de imágenes web + +La interfaz web actualmente no puede prevenir el uso de combinaciones de +opciones no válidas, y en particular, cuando el cambio de una opción que +normalmente (es decir, utilizando live-build directamente) cambiaría los +valores predeterminados de otras opciones que figuran en el formulario web, +el constructor web no cambia estos valores predeterminados. En particular, +si se cambia #{--architectures}# del valor por defecto #{i386}# a #{amd64}#, +se debe cambiar la opción correspondiente #{--linux-flavours}# del valor por +defecto #{586}# a #{amd64}#. Ver la página de manual de #{lb_config}# para +para más detalles sobre la versión de live-build instalada en el constructor +web. El número de versión de live-build aparece en la parte inferior de la +página web del servicio de creación de imágenes. + +El tiempo de creación de la imagen mostrado en la web es sólo una estimación +aproximada y puede no reflejar con exactitud la duración que la construcción +de la imagen realmente necesita. Tampoco se actualiza esta estimación una +vez mostrada. Hay que tener un poco de paciencia. No volver a recargar la +página, ya que esto puede volver a lanzar una nueva creación de otra imagen +con los mismos parámetros. {Ponerse en contacto}#contact con nosotros si no +se recibe la notificación de que la imagen está terminada una vez que se +esté seguro de que se ha esperado lo suficiente y verificado que la +notificación por correo electrónico no ha ido a parar a la bandeja de spam. + +El servicio web está limitado en el tipo de imágenes que se pueden +construir. Esto lo hace simple y a la vez eficiente de usar y mantener. Si +se desea realizar personalizaciones que no se contemplan en la interfaz web, +en el resto de este manual se explica cómo crear imágenes propias con +live-build. + +2~building-iso-hybrid Primeros pasos: creación de una imagen ISO híbrida + +Independientemente del tipo de imagen, cada vez se tendrá que realizar los +mismos pasos básicos para construir una imagen. Como primer ejemplo, crear +un directorio de trabajo, cambiar a ese directorio y ejecutar la siguiente +secuencia de comandos live-build para crear una imagen ISO híbrida básica +que contiene sólo el sistema por defecto de Debian sin X.org. Es adecuada +para grabarla en un CD o DVD y también para copiarla en un dispositivo USB. + +El nombre del directorio de trabajo es indiferente, pero si se da un vistazo +a los ejemplos utilizados en live-manual, es una buena idea utilizar un +nombre que ayude a identificar la imagen con la que está trabajando en cada +directorio, especialmente si se está trabajando o experimentando con +distintos tipos de imágenes. En este caso, vamos a construir un sistema +utilizando los valores por defecto, así que lo vamos a llamar, por ejemplo, +live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Entonces, ejecutar el comando #{lb config}#. Esto creará una jerarquía +«config/» en el directorio actual que será usada por otros comandos: + +code{ + + $ lb config + +}code + +Al no pasar ningún parámetro a estos comandos, se utilizarán todas las +opciones por defecto. Ver {El comando lb config}#lb-config para más +detalles. + +Ahora que existe un jerarquía «config/», se puede crear la imagen con el +comando #{lb build}#: + +code{ + + # lb build + +}code + +Este proceso puede llevar un tiempo, dependiendo de la velocidad del +ordenador y de la conexión de red. Cuando haya terminado, debería haber un +fichero #{live-image-i386.hybrid.iso}# listo para ser usado en el directorio +actual. + +*{Nota:}* Si se está construyendo en un sistema amd64 el nombre de la imagen resultante será #{live-image-amd64.hybrid.iso}#. Tener en cuenta esta convención a lo largo del manual. + +2~using-iso-hybrid Usar una imagen ISO híbrida + +Después de construir o descargar una imagen ISO híbrida, las cuales se +pueden obtener en https://www.debian.org/CD/live/, el siguiente paso +habitual es preparar el medio de almacenamiento, ya sea medios ópticos +CD-R(W) o DVD-R(W) o llaves USB. + +3~burning-iso-image Grabar una imagen ISO en un medio físico. + +Grabar una imagen ISO es fácil. Simplemente instalar /{xorriso}/ y usarlo +desde el intérprete de comandos para grabar la imagen. Por ejemplo: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copiar una imagen ISO híbrida a un dispositivo +USB + +Las imágenes ISO preparadas con #{xorriso}#, pueden sencillamente copiarse a +una llave USB con la orden #{cp}# o con un programa equivalente. Insertar +una llave USB con un tamaño suficiente para la imagen y determinar qué +dispositivo es, al cual nos referiremos de ahora en adelante como +#{${USBSTICK}}#. Este nombre de «dispositivo» se refiere a la llave entera +como por ejemplo #{/dev/sdb}# y ¡No a una partición como #{/dev/sdb1}#! Se +puede encontrar el nombre del dispositivo correcto mirando la salida de +#{dmesg}# después de conectar la llave, o mejor aún, ejecutando #{ls -l +/dev/disk/by-id}#. + +Cuando se esté seguro de tener el nombre del dispositivo correcto, usar la +orden #{cp}# para copiar la imagen a la llave. *{¡Esto borrará de forma +definitiva cualquier contenido previo en la llave!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Nota:}* El comando /{sync}/ se utiliza para asegurarse de que todos los datos, que el kernel almacena en la memoria mientras se copia la imagen, se escriben en la llave USB. + +3~using-usb-extra-space Usar el espacio libre en el dispositivo USB + +Después de copiar la #{live-image-i386.hybrid.iso}# en una llave USB, la +primera partición del dispositivo será utilizada por el sistema en vivo. Si +se desea utilizar el espacio libre, se puede utilizar un programa de +particionado como /{gparted}/ o /{parted}/ para crear una partición nueva en +la llave. + +code{ + + # gparted ${USBSTICK} + +}code + +Después de crear la partición, dónde #{${PARTITION}}# es el nombre de la +partición, por ejemplo #{/dev/sdb2}# se tiene que crear un sistema de +ficheros en él. Una opción posible sería ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Nota:}* Si se desea usar el espacio extra con Windows, segun parece, ese sistema operativo no puede acceder normalmente a otra partición más que a la primera. Se han comentado algunas soluciones a este problema en nuestra {lista de correo}#contact pero según parece no hay una solución fácil. + +*{Recordar: Cada vez que se instale una nueva live-image-i386.hybrid.iso en el dispositivo, todos los datos del dispositivo se perderán debido a que la tabla de particiones se sobrescribe con el contenido de la imagen, así pues, realizar primero una copia de seguridad de la partición para poder restaurarla trás actualizar la imagen en vivo.}* + +3~booting-live-medium Arrancar el medio en vivo + +La primera vez que se arranque desde el medio de almacenamiento en vivo, ya +sea CD, DVD, llave USB, o de arranque en red PXE, primero puede ser +necesario algún tipo de configuración en la BIOS de la máquina. Dado que las +BIOS varían mucho en sus características y combinaciones de teclas, no se +puede entrar en el tema en profundidad aquí. Algunas BIOS proporcionan una +tecla para abrir un menú de dispositivos de arranque que es la manera más +fácil de hacerlo si se encuentra disponible en el sistema. De lo contrario, +se tiene que entrar en el menú de configuración de la BIOS y cambiar el +orden de arranque y colocar el dispositivo de arranque del sistema en vivo +antes que el dispositivo de arranque habitual. + +Una vez que se haya arrancado desde el medio de almacenamiento, se accede a +un menú de arranque. Si se pulsa la tecla «enter», el sistema arrancará +usando el modo por defecto #{Live}# y las opciones predeterminadas. Para +obtener más información acerca de las opciones de arranque, ver la opción +«help» del menú y también las páginas del manual de live-boot y live-config +que se encuentran en el sistema en vivo. + +Suponiendo que se ha seleccionado #{Live}# y arrancado una imagen en vivo +por defecto con escritorio gráfico, después de que los mensajes de arranque +hayan pasado, se habrá iniciado automáticamente una sesión como usuario +#{user}# y se verá el escritorio preparado para ser usado. Si se ha +arrancado una imagen sólo de consola como por ejemplo una imagen +#{standard}# de {las imágenes prefabricadas}#downloading-prebuilt-images, se +habrá iniciado automáticamente una sesión como usuario #{user}# y se verá el +cursor del intérprete de comandos preparado para ser usado. + +2~using-virtual-machine Usar una máquina virtual para pruebas + +Ejecutar las imágenes en vivo en una máquina virtual (VM) puede ser un gran +ahorro de tiempo para su desarrollo. Esto no está exento de advertencias: + +_* Para ejecutar una máquina virtual se requiere tener suficiente memoria +RAM para el sistema operativo huésped y el anfitrión y se recomienda una CPU +con soporte de hardware para la virtualización. + +_* Existen algunas limitaciones inherentes a la ejecución en una máquina +virtual, por ejemplo, rendimiento de video pobre o limitada gama de hardware +emulado. + +_* Cuando se desarrolla para un hardware específico, no hay sustituto mejor +que el propio hardware. + +_* A veces hay errores causados únicamente por la ejecución en una máquina +virtual. En caso de duda, probar la imagen directamente en el hardware. + +Siempre que se pueda trabajar dentro de estas limitaciones, mirar que +software VM hay disponible y elegir uno que sea adecuado según las +necesidades. + +3~testing-iso-with-qemu Probar una imagen ISO con QEMU + +La máquina virtual más versátil en Debian es QEMU. Si el procesador tiene +soporte de hardware para virtualización, utilizar el paquete +/{qemu-kvm}/. En la descripción del paquete /{qemu-kvm}/ se enumera +brevemente la lista de requisitos. + +En primer lugar, instalar #{qemu-kvm}# si el procesador lo soporta. Si no es +así, instalar #{qemu}#, en cuyo caso el nombre del programa será #{qemu}# en +vez de #{kvm}# en los siguientes ejemplos. El paquete /{qemu-utils}/ también +es útil para la creación de imágenes virtuales de disco con #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Arrancar una imagen ISO es sencillo: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +Consultar las páginas del manual para más detalles. + +3~testing-iso-with-virtualbox Probar una imagen ISO con VirtualBox + +Para probar una imagen ISO con /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Crear una nueva máquina virtual, cambiar la configuración de almacenamiento +para utilizar #{live-image-i386.hybrid.iso}# como dispositivo CD/DVD y +arrancar la máquina. + +*{Nota:}* Para probar los sistemas en vivo con soporte X.org en /{virtualbox}/, se puede incluir el paquete del driver de VirtualBox X.org, /{virtualbox-guest-dkms}/ y /{virtualbox-guest-x11}/, en la configuración de live-build. De lo contrario, la resolución se limita a 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +Para que el paquete dkms funcione, hace falta tener instalados también los +kernel-headers para la variante del kernel utilizado. En lugar de enumerar +manualmente el paquete /{linux-headers}/ correspondiente en la lista de +paquetes creados anteriormente, live-build puede seleccionarlo +automáticamente. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Construir y utilizar una imágen HDD + +Crear una imagen HDD es similar a una de tipo ISO híbrida en todos los +aspectos, con la diferencia de que hay que especificar #{-b hdd}# y de que +el nombre de la imagen final es #{live-image-i386.img}# que no se puede +copiar en medios ópticos. Es adecuada para el arranque desde dispositivos +USB, discos duros USB y otros sistemas de almacenamiento +portable. Normalmente, se puede utilizar para este propósito una imagen ISO +híbrida, pero es posible que la BIOS no maneje adecuadamente las imágenes +híbridas, entonces es mejor utilizar una imagen hdd. + +*{Nota:}* si se ha creado una imagen ISO híbrida con el ejemplo anterior, se tendrá que limpiar el directorio de trabajo con el comando #{lb clean}# (ver {El comando lb clean}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Ejecutar el comando #{lb config}# como antes pero esta vez especificando el +tipo de imagen HDD: + +code{ + + $ lb config -b hdd + +}code + +Crear ahora la imagen con el comando #{lb build}#: + +code{ + + # lb build + +}code + +Cuando termine el proceso de creación, debe haber un fichero llamado +#{live-image-i386.img}# en el directorio actual . + +La imagen binaria generada contiene una partición VFAT y el gestor de +arranque syslinux, lista para ser copiada directamente en un dispositivo +USB. De nuevo, dado que utilizar una imagen HDD es igual a usar una imagen +ISO híbrida en un USB, seguir las instrucciones de {Usar una imagen ISO +híbrida}#using-iso-hybrid con la diferencia del nombre, +#{live-image-i386.img}# en lugar de #{live-image-i386.hybrid.iso}#. + +Del mismo modo, para probar una imagen HDD con Qemu, instalar /{qemu}/ como +se describe más arriba en {Probar una imágen ISO con +QEMU}#testing-iso-with-qemu. A continuación, ejecutar #{kvm}# o #{qemu}#, +según qué versión necesita el sistema anfitrión y especificando +#{live-image-i386.img}# como primer disco duro. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Creación de una imagen de arranque en red + +La siguiente secuencia de comandos creará una imagen de arranque en red +básica que contendrá el sistema por defecto de Debian sin X.org. Se puede +usar para el arranque en red. + +*{Nota:}* si se ha seguido algúno de los ejemplos anteriores, se tendrá que limpiar el directorio de trabajo con el comando #{lb clean}#: + +code{ + + # lb clean + +}code + +En este caso concreto, un #{lb clean --binary}# no sería suficiente para +eliminar las etapas necesarias. La razón de esto es que en las +configuraciones de arranque en red, se debe utilizar una configuración +initramfs diferente que live-build ejecuta automáticamente al crear imágenes +netboot. Ya que la creación del initramfs pertenece a la etapa chroot, +realizar el cambio a netboot en un directorio de construcción ya existente +significa reconstruir la etapa chroot también. Por lo tanto, se tiene que +ejecutar un #{lb clean}# (que también eliminará la etapa chroot). + +Ejecutar el comando #{lb config}# de la siguiente manera para configurar la +imagen de arranque en red: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +A diferencia de las imágenes ISO y HDD, el sistema de arranque en red en sí +mismo no envía la imagen del sistema de ficheros al cliente, por eso los +ficheros se deben enviar mediante NFS. Con lb config se puede seleccionar +diferentes sistemas de ficheros en red. Las opciones #{--net-root-path}# y +#{--net-root-server}# especifican la ubicación y el servidor, +respectivamente, del servidor NFS en el que se encuentra la imagen del +sistema de ficheros en el arranque. Se debe asegurar que estos se ajustan a +los valores adecuados para la red y el servidor deseados. + +Crear ahora la imagen con el comando #{lb build}#: + +code{ + + # lb build + +}code + +En un arranque en red, el cliente ejecuta una pequeña pieza de software que +generalmente se encuentra en la EPROM de la tarjeta Ethernet. Este programa +envía una solicitud de DHCP para obtener una dirección IP e información +sobre qué hacer a continuación. Por lo general, el siguiente paso es +conseguir un gestor de arranque de alto nivel a través del protocolo +TFTP. Este gestor podría ser PXELINUX, GRUB, o incluso arrancar directamente +un sistema operativo como Linux. + +Por ejemplo, si se descomprime el archivo generado +#{live-image-i386.netboot.tar}# en el directorio #{/srv/debian-live}#, se +verá la imagen del sistema de ficheros en #{live/filesystem.squashfs}# y el +kernel, initrd y el gestor de arranque pxelinux en #{tftpboot/}#. + +Ahora se debe configurar tres servicios en el servidor para el arranque en +red: el servidor DHCP, el servidor TFTP y el servidor NFS. + +3~ Servidor DHCP + +Hay que configurar el servidor DHCP de red para asegurar que proporciona una +dirección IP al cliente, y para anunciar la ubicación del gestor de arranque +PXE. + +He aquí un ejemplo que puede servir de inspiración. Fue escrito para el +servidor ISC DHCP #{isc-dhcp-server}# en su fichero de configuración +#{/etc/dhcp/dhcpd.conf}#: + +code{ + + # /etc/dhcp/dhcpd.conf - fichero de configuración para isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Servidor TFTP + +Se encarga de suministrar el kernel y el Disco RAM inicial para el sistema. + +Se debe instalar el paquete /{tftpd-hpa}/. Este servidor podrá suministrar +todos los ficheros contenidos de un directorio raíz, normalmente +#{/srv/tftp}#. Para permitirle que pueda servir los ficheros de +#{/srv/debian-live/tftpboot}#, se debe ejecutar el siguiente comando con +privilegios de superusuario: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +y escribir el directorio del nuevo servidor tftp cuando sea requerido. + +3~ Servidor NFS + +Una vez el equipo cliente ha descargado y arrancado el kernel de Linux junto +a su initrd, intentará montar el sistema de archivos de la imagen en vivo a +través de un servidor NFS. + +Se debe instalar el paquete /{nfs-kernel-server}/. + +Entonces, se debe hacer que la imagen del sistema de archivos esté +disponible a través de NFS añadiendo una línea como la siguiente para +#{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +e informar al servidor NFS sobre esta nueva exportación con el siguiente +comando: + +code{ + + # exportfs -rv + +}code + +La configuración de estos tres servicios puede ser un poco difícil. Será +necesario un poco de paciencia para conseguir que todos ellos funcionen +juntos. Para obtener más información, ver el wiki de syslinux en +http://www.syslinux.org/wiki/index.php/PXELINUX o la sección sobre TFTP Net +Booting del Manual del Instalador de Debian en +http://d-i.alioth.debian.org/manual/es.i386/ch04s05.html Esto puede ser +útil, ya que sus procesos son muy similares. + +3~ Cómo probar el arranque en red + +La creación de una imagen de arranque en red es sencilla con live-build, +pero probar las imágenes en máquinas físicas puede ser un proceso mucho más +lento. + +Para hacer nuestra vida más fácil, se puede utilizar la virtualización. + +3~ Qemu + +_* Instalar /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Se debe editar el fichero #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Obtener o crear un #{grub-floppy-netboot}#. + +Lanzar #{qemu}# con "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Arrancar desde internet + +Arrancar desde internet, o Webbooting, es una manera muy adecuada de +descargar y arrancar sistemas en vivo utilizando internet como medio, ya que +hay muy pocos requisitos para arrancar desde internet utilizando +webbooting. Por un lado, se necesita un medio en vivo con un gestor de +arranque, un disco ram inicial y un kernel. Por otro lado, un servidor web +para almacenar los ficheros squashfs que contienen el sistema de ficheros. + +3~ Conseguir los ficheros para arrancar desde internet + +Como de costumbre, se puede construir las imágenes uno mismo o utilizar +alguna de las imágenes prefabricadas, disponibles en la página web del +proyecto http://live-systems.org/. Utilizar las imágenes prefabricadas es +muy práctico para hacer pruebas hasta que se está seguro de cuales son las +necesidades reales. Si ya se ha construido una imagen, los ficheros +necesarios para el arranque desde internet se encuentran en el directorio +#{binary/live/}#. Los ficheros se llaman #{vmlinuz}#, #{initrd.img}# y +#{filesystem.squashfs}#. + +También es posible extraer los ficheros de una imagen iso ya existente. Para +ello, hay que montar la imagen de la siguiente manera: + +code{ + + # mount -o loop image.iso /mnt + +}code + +Los ficheros se encuentran en el directorio #{live/}#. En este caso +concreto, sería #{/mnt/live/}#. Este método tiene la desventaja de que es +necesario ser root para poder montar la imagen. Sin embargo, tiene la +ventaja de que es fácil hacerlo con un script y por lo tanto, fácil de +automatizar. + +Pero, sin duda alguna, la forma más fácil de extraer los ficheros de una +imagen iso y subirlos al servidor web al mismo tiempo, es utilizando el +midnight commander o /{mc}/. Si se tiene el paquete /{genisoimage}/ +instalado, este administrador de ficheros de dos paneles permite examinar el +contenido de un archivo iso en un panel y subir los ficheros a través de ftp +en el otro panel. A pesar de que este método requiere un trabajo manual, no +requiere privilegios de root. + +3~ Arrancar imágenes webboot + +Aunque algunos usuarios pueden preferir la virtualización para probar el +arranque desde internet, en este caso se utiliza hardware real para ilustrar +el caso de uso que se explica a continuación y que debe considerarse sólo +como un ejemplo. + +Para arrancar una imagen webboot es suficiente copiar los elementos +mencionados anteriormente, es decir, #{vmlinuz}# y #{initrd.img}# en una +llave usb dentro de un directorio llamado #{live/}# e instalar syslinux como +gestor de arranque. Entonces, arrancar desde la llave usb y teclear +#{fetch=URL/RUTA/AL/FICHERO}# en las opciones de arranque. live-boot se +encargará de descargar el archivo squashfs y almacenarlo en la memoria +ram. De este modo, es posible utilizar el sistema de ficheros comprimido +descargado como si fuera un sistema en vivo normal. Por ejemplo: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Caso de uso:}* Se tiene dos archivos squashfs almacenados en un servidor web, uno que contiene un escritorio completo, como gnome, y uno standard. Si se necesita un entorno gráfico para una máquina, se puede insertar la llave usb y arrancar desde internet la imagen gnome. Si se necesita una de las herramientas incluidas en el segundo tipo de imagen, quizás para otra máquina, se puede arrancar desde internet la imagen standard. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-binary.ssi new file mode 100644 index 0000000..f522d7a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-binary.ssi @@ -0,0 +1,66 @@ +:B~ Personalización de la imagen binaria + +1~customizing-binary Personalización de la imagen binaria + +2~ Gestores de arranque + +live-build utiliza /{syslinux}/ y algunos de sus derivados (en función del +tipo de imagen) como gestores de arranque por defecto. Se pueden +personalizar fácilmente para satisfacer todas las necesidades. + +Para utilizar un tema completo, copiar #{/usr/share/live/build/bootloaders}# +en #{config/bootloaders}# y editar los ficheros allí. Si no se desea +modificar todas las configuraciones de los gestores de arranque disponibles, +es suficiente con sólo proporcionar una copia local personalizada de uno, +por ejemplo, copiar la configuración de *{isolinux}* en +#{config/bootloaders/isolinux}# es suficiente, dependiendo del caso de uso. + +Cuando se modifica uno de los temas predeterminados, si se quiere utilizar +una imagen de fondo personalizada que se mostrará junto con el menú de +arranque, añadir una imagen splash.png de 640x480 píxeles. Y entonces, +borrar el fichero splash.svg. + +Hay muchas posibilidades a la hora de hacer cambios. Por ejemplo, los +derivados de syslinux están configurados por defecto con un tiempo de espera +de 0 (cero) lo que significa que harán una pausa indefinida en su pantalla +de inicio hasta que se pulse una tecla. + +Para modificar el tiempo de espera de arranque de una imagen #{iso-hybrid}# +se puede editar el fichero *{isolinux.cfg}* especificando el tiempo en +unidades de segundo 1/10. Un fichero *{isolinux.cfg}* modificado para +arrancar después de cinco segundos sería así: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ Metadatos ISO + +Al crear una imagen binaria ISO9660 se pueden utilizar las siguientes +opciones para añadir varios metadatos textuales a la imagen. Esto puede +ayudar a identificar fácilmente la versión o la configuración de una imagen +sin arrancarla. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: Esto debería especificar +la aplicación que estará en la imagen. La longitud máxima para este campo es +de 128 caracteres. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: Esto debería identificar quién +prepara la imagen, por lo general con algunos detalles de contacto. El valor +predeterminado para esta opción es la versión de live-build que se está +utilizando, lo que puede ayudar con la posterior depuración de errores. La +longitud máxima para este campo es de 128 caracteres. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: Esto debería identificar quién +publica la imagen, por lo general con algunos detalles de contacto. La +longitud máxima para este campo es de 128 caracteres. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: Esto debería especificar el volumen +de identificación de la imagen. Esto se utiliza como etiqueta visible para +el usuario en algunas plataformas como Windows y Apple Mac OS. La longitud +máxima para este campo es de 32 caracteres. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-contents.ssi new file mode 100644 index 0000000..c86549b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-contents.ssi @@ -0,0 +1,155 @@ +:B~ Personalización de contenidos + +1~customizing-contents Personalización de contenidos + +Este capítulo trata, no solamente de una mera descripción de cómo +seleccionar los paquetes a incluir en el sistema en vivo, sino que además +presenta cómo hacer el «ajuste fino» de la personalización de los contenidos +del propio sistema. Los «includes» permiten adjuntar o reemplazar cualquier +fichero en la imagen en vivo a crear, los scripts gancho (hooks) permiten +ejecutar cualquier orden en las diferentes etapas de creación y en el +momento del arranque y por último, la preconfiguración permite configurar +paquetes cuando son instalados, suministrando las respuestas a las preguntas +de debconf. + +2~includes Includes + +Idealmente, un sistema en vivo debería incluir solamente los ficheros +proporcionados por los paquetes sin modificar. Sin embargo, algunas veces es +conveniente incluir o modificar algún contenido mediante ficheros. La +utilización de includes posibilita la inclusión, modificación o cambio de +cualquier fichero en la imagen en vivo a crear. live-build utiliza dos +mecanismos: + +_* Includes locales en chroot : Estos includes permiten incluir o reemplazar +ficheros en el sistema de ficheros chroot. Para más información ver +{Includes locales en Live/chroot}#live-chroot-local-includes + +_* Includes locales en Binary: Estos includes permiten incluir o reemplazar +ficheros en la propia imagen binaria generada. Para más información ver +{Includes locales en Binary}#binary-local-includes + +Para más infomación acerca de la diferencia entre las imágenes "Live" y +"binary" ver {Términos}#terms + +3~live-chroot-local-includes Includes locales en Live/chroot + +Los includes locales en chroot se utilizan para incluir o reemplazar +ficheros en el sistema de ficheros Live/chroot de manera que puedan ser +utilizados en el sistema en vivo. Una utilización típica de estos includes +puede ser rellenar el directorio (#{/etc/skel}#) usado por el sistema Live +para crear el directorio home del usuario. Otra utilización típica es +suministrar ficheros de configuración que pueden ser incluidos o +reemplazados en la imagen sin necesidad de realizar procesado alguno; Si se +necesita realizar algún procesado de estos ficheros ver la sección {Scripts +gancho locales en Live/chroot}#live-chroot-local-hooks + +Para incluir ficheros solamente hace falta añadirlos al directorio de +configuración #{config/includes.chroot}#. Habrá una relación directa entre +este directorio y el directorio raíz #{/}# del sistema en vivo. Por ejemplo, +si se desea añadir un fichero para que sea el fichero +#{/var/www/index.html}# del sistema en vivo se puede hacer lo siguiente: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +El directorio de configuración presentará la siguiente jerarquía: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Los includes locales en chroot serán instalados después de la instalación de +los paquetes de manera que los includes sobreescribirán cualquier fichero +que los paquetes puedan haber instalado. + +3~binary-local-includes Includes locales en Binary + +Se puede incluir material como documentación, videos, etc en el sistema de +ficheros del medio (USB, CDROM, etc) donde se grabará la imagen de manera +que sea accesible nada más insertar el medio sin necesidad de arrancar el +sistema en vivo. Para esto se utilizan los includes locales en +Binary. Funciona de manera similar a los includes locales en chroot +comentados anteriormente. Por ejemplo, supongamos que en el medio de +instalación se desea añadir unos ficheros con videos de demostración +#{~/video_demo.*}# sobre el funcionamiento del sistema en vivo de manera que +el usuario pueda acceder a ellos a través de la página de indice +HTML. Simplemente se debe copiar el material en #{config/includes.binary/}# +de la siguiente manera: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +Los ficheros aparecerán ahora en el directorio raíz del medio en vivo. + +2~hooks Scripts gancho (Hooks) + +Los scripts gancho permiten ejecutar órdenes para personalizar la imagen en +las etapas chroot y binary. + +3~live-chroot-local-hooks Scripts gancho locales en Live/chroot + +Para ejecutar órdenes en la etapa chroot se deben crear scripts gancho +(hooks) con el sufijo #{.hook.chroot}# que contengan dichas ordenes a +ejecutar y depositarlos en el directorio #{config/hooks/}#. Estos scripts +serán ejecutados en el entorno del chroot después de que el resto de las +tareas de preparación del chroot han sido realizadas. Se debe asegurar que +previamente se han instalado en el entorno chroot cualquier paquete, fichero +u órden que necesiten los scripts gancho. El paquete live-build instala en +el directorio #{/usr/share/doc/live-build/examples/hooks}# del sistema +huésped unos cuantos scripts gancho para realizar tareas habituales de +personalización del entorno chroot que pueden ser copiados o referenciados +mediante enlace simbólico en la propia configuración. + +3~boot-time-hooks Scripts gancho en tiempo de arranque + +Para ejecutar ordenes en el arranque del sistema en vivo, se puede +suministrar scripts gancho a live-config depositándolos en el directorio +#{config/includes.chroot/lib/live/config/}#, tal y como se explica en la +sección de "Personalización" de la página de manual de live-config. Es +interesante examinar los scripts gancho que trae de serie live-config que +pueden verse en #{/lib/live/config/}# y fijarse en la secuencia de +números. Cuando se vaya a utilizar scripts propios deben ser prefijados con +un número para indicar el orden de ejecución. Otra posibilidad es utilizar +un paquete personalizado tal y como se describe en {Instalar paquetes +modificados o de terceros}#installing-modified-or-third-party-packages. + +3~ Scripts gancho locales en Binary + +Para ejecutar comandos en la etapa Binary se deben crear scripts gancho con +el sufijo #{.hook.binary}# que contengan las ordenes y depositarlos en el +directorio #{config/hooks/}#. Los scripts gancho se ejecutarán después de +finalizar el resto de procesos de la etapa pero antes de crear los checksum +con binary_checksum que es el último proceso que se ejecuta en esta +etapa. Los scripts gancho no se ejecutan en el entorno del chroot, así que +hay que tener cuidado de no modificar cualquier fichero fuera del árbol de +creación, o se dañará el sistema de creación. En +#{/usr/share/doc/live-build/examples/hooks}# se pueden ver varios ejemplos +de scripts gancho genéricos que permiten tareas de personalización para la +etapa Binary. Estos scripts pueden ser utilizados en la propia configuración +copiándolos o creando enlaces simbólicos. + +2~ Preconfiguración de las preguntas de Debconf + +Los ficheros del directorio #{config/preseed/}# con el sufijo #{.cfg}# +seguido por la etapa (#{.chroot}# o #{.binary}#) son ficheros de +preconfiguración para debconf. live-build instalará estos ficheros mediante +#{debconf-set-selections}# durante la etapa correspondiente. + +Ver #{debconf(7)}# en el paquete /{debconf}/ para obtener más información +acerca de debconf. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-installer.ssi new file mode 100644 index 0000000..d76e052 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-installer.ssi @@ -0,0 +1,92 @@ +:B~ Personalización del Instalador de Debian + +1~customizing-installer Personalización del Instalador de Debian + +Las imágenes de los sistemas en vivo pueden integrarse con el Instalador de +Debian. Hay varios tipos de instalación que se diferencian en qué se incluye +en la imágen y en cómo opera el instalador. + +En esta sección se debe estar atento a la utilización de las +mayúsculas. Cuando se utiliza «Instalador de Debian», con mayúsculas, se +hace referencia explícita al instalador oficial del sistema Debian, y a nada +más ni a ningún otro instalador. A menudo se abrevia con «d-i». + +2~ Tipos de imágenes según el instalador + +Principalmente existen tres tipos de imágenes según el instalador: + +*{Imágenes con Instalador Debian «normal»}*: Esta imagen en vivo se puede considerar como la imagen habitual. Dispone de un kernel y un initrd diferenciados que, al ser seleccionados desde el gestor de arranque, ejecutan un Instalador de Debian estándar, de la misma manera que lo harían si se arrancase desde una imagen de CD descargada desde el sitio oficial de Debian. Las imágenes que contienen un sistema en vivo con otro instalador independiente se suelen llamar «imágenes combinadas». + +En estas imágenes, el sistema operativo Debian se instala mediante la +herramienta /{debootstrap}/ que descarga paquetes .deb desde medios locales +o por red. El resultado final es un sistema Debian por defecto instalado en +el disco duro. + +El conjunto de este proceso puede ser preconfigurado (preseeded) y +personalizado de muchas maneras; Para más información, ver las páginas +relevantes en el manual del Instalador de Debian. Una vez que se ha generado +el fichero de preconfiguración adecuado a las necesidades, live-build puede +encargarse de depositarlo en la imagen y activarlo de forma automática. + +*{Imágenes con Instalador Debian «Live»}*: Estas imágenes en vivo también disponen de un kernel y un initrd diferenciados que, al ser seleccionados desde el gestor de arranque, ejecutan un Instalador de Debian. + +El procedimiento de instalación es idéntico al realizado por las imagenes +«Regulares» pero, en lugar de utilizar /{debootstrap}/ para obtener e +instalar paquetes .deb, lo que hace es copiar al disco duro la imagen del +sistema de ficheros que se había preparado para lanzar el sistema en +vivo. Esto se logra mediante un .udeb especial llamado live-installer. + +Una vez finalizada esta etapa, el Instalador de Debian continua normalmente, +instalando y configurando los siguientes elementos como pueden ser gestor de +arranque, creación de usuarios locales, etc. + +*{Nota:}* Para poder incluir los dos tipos de instalador, «normal» y «live», en el mismo medio, se debe deshabilitar el live-installer. Esto se hace utilizando la variable de preconfiguración (preseed) #{live-installer/enable=false}#. + +*{Instalador Debian «del escritorio»}*: Una vez el sistema en vivo está ejecutandose, se puede lanzar el Instalador de Debian haciendo clic en el icono correspondiente, sin importar el tipo de Instalador Debian utilizado en el arranque. Esta manera de instalar Debian es más sencilla para el usuario y aconsejable en algunas situaciones. Para poder realizar esta acción se debe instalar el paquete debian-installer-launcher. + +Por defecto, live-build no incluye las imágenes que utilizan el Instalador +de Debian. Esto debe ser habilitado de forma específica en #{lb +config}#. También hay que hacer notar que, para que la instalación desde «el +escritorio» funcione, el kernel del sistema en vivo debe ser el mismo que el +kernel que utiliza #{d-i}# en la arquitectura especificada. Por ejemplo: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Personalizando el Instalador de Debian mediante preconfiguración + +Tal y como se describe en el apéndice B del manual del Instalador de Debian +que puede consultarse en +https://www.debian.org/releases/stable/i386/apb.html, «La preconfiguración +permite asociar respuestas a preguntas que aparecen en el proceso de +instalación, sin tener que responderlas manualmente en el momento se se +ejecuta dicho proceso. Esto hace posible automatizar totalmente la mayoria +de las instalaciones e incluso ofrece alguna característica que no está +disponible durante una instalación normal.» Con live-build se puede llevar +a cabo esta personalización depositando un fichero llamado #{preseed.cfg}# +en el directorio de configuración #{config/includes.installer/}#. Por +ejemplo, para preconfigurar la variante local a #{en_US}# se puede hacer: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Personalizar el contenido del Instalador de Debian + +Es posible que, con propósitos experimentales o para depuración de errores, +se desee incluir paquetes udeb creados localmente para el #{d-i}#. Estos +paquetes udeb son componentes del Instalador de Debian que definen su +comportamiento. Para incluirlos en la imagen, basta con depositarlos en el +directorio de configuración #{config/packages.binary/}#. También pueden +incluirse o reemplazarse ficheros y directorios en el initrd del instalador +de una manera similar a la que se describe en {Includes locales en +Live/chroot}#live-chroot-local-includes, depositando el material en el +directorio #{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-overview.ssi new file mode 100644 index 0000000..1bc7b36 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-overview.ssi @@ -0,0 +1,92 @@ +:B~ Personalización de contenidos + +1~customization-overview Descripción general de la personalización. + +Este capítulo presenta un resumen de las diversas formas en que se puede +personalizar un sistema en vivo. + +2~ Configuración en el momento de la creación vs en el momento del arranque + +Las opciones de configuración de un sistema Debian Live se pueden dividir en +opciones que se aplican en el momento de la creación de la imágen del +sistema en vivo y opciones que se tendrán en cuenta cuando el sistema en +vivo arranque. Estas últimas se puenden dividir a su vez en opciones que se +ejecutan en la etapa inicial del arranque, aplicadas por el paquete +live-boot, y otras que se llevarán a cabo posteriormente y que son aplicadas +por el paquete live-config. Cualquier opción en tiempo de arraque puede ser +modificada por el usuario indicándola en los parámetros de arranque del +kernel mediante el indicador de arranque. La imagen puede ser creada por +defecto con los parámetros de arranque adecuados, de manera que los usuarios +solamente tendrán que arrancar el sistema en vivo, directamente, sin +necesidad de especificar ninguna opción adicional, ya que las opciones por +defecto serán las adecuadas. En particular, la opcion #{lb +--bootappend-live}# permite introducir cualquier parámetro del kernel para +el sistema en vivo, como pueden ser la persistencia, distribución del +teclado, zonas horarias, etc. Ver un ejemplo en {Personalización de las +variantes locales e idioma}#customizing-locale-and-language. + +Las opciones de configuración en tiempo de creación se describen en la +página de manual del comando #{lb config}#. Las opciones en tiempo de +arranque se describen en las páginas de manual de los paquetes live-boot y +live-config. Aunque los paquetes live-boot y live-config se instalan en el +sistema en vivo que se está creando, también se recomienda que sean +instalados en el sistema huésped, que se utiliza para crear la imagen del +sistema en vivo, con el fin de facilitar la referencia cuando se trabaja en +una configuración. No hay ningún problema en hacerlo, ya que ninguno de los +scripts que contiene el sistema huésped será ejecutado, a menos que se +configure el sistema huésped como sistema en vivo. + +2~stages-of-the-build Etapas de la creación + +El proceso de creación de la imagen está dividido en etapas en las que se +aplican diferentes personalizaciones en cada una de ellas. La primera etapa +que se ejecuta es la etapa *{bootstrap}*. Esta fase inicial crea y rellena +el directorio chroot con paquetes que constituyen un sistema Debian +básico. A continuación la etapa *{chroot}* completa la creación del +directorio chroot, rellenándolo con todos los paquetes que han sido listados +en la configuración y material adicional. En esta etapa se utiliza la +mayoría de las personalizaciones de contenido. La etapa *{binary}* es la +etapa final en la que se prepara la imagen del sistema en vivo utilizando el +contenido del directorio chroot para construir el sistema de ficheros raíz +del futuro sistema en vivo, se incluye el instalador y cualquier otro +material adicional de la imagen que no es parte el sistema de ficheros raíz, +como puede ser el gestor de arranque (bootloader) o ficheros de +documentación. Posteriormente, en la etapa opcional *{source}* se creará el +fichero comprimido (tarball) que contiene los ficheros de código fuente de +los paquetes utilizados. + +En cada una de estas etapas hay una secuencia particular en la se aplican +las acciones a realizar. Estas acciones son organizadas en forma de capas de +tal manera que aseguran la personalización de una manera razonable. Por +ejemplo, dentro de la etapa *{chroot}*, las preconfiguraciones (preseeds) se +aplican antes que cualquier paquete sea instalado, los paquetes son +instalados antes de incluir ningún fichero localmente y los scripts gancho +(hooks) serán ejecutados al final de todo, una vez que todos los materiales +están ubicados en su lugar. + +2~ Opciones para lb config en ficheros + +Aunque la orden #{lb config}# crea un esqueleto de configuración en el +directorio #{config/}#, quizás sea necesario escribir ficheros de +configuración adicionales dentro de la jerarquía de subdirectorios de +#{config/}# con el fin de alcanzar los objetivos propuestos. En el proceso +de creación de la imagen estos ficheros adicionales serán copiados o en el +sistema de ficheros que se utilizará en el sistema en vivo, o en el sistema +de ficheros de la propia imagen binaria o quizás podrán suministrar opciones +de configuracion al sistema en vivo que sería incomodo pasar en la línea de +parámetros del kernel. Esto dependerá de en qué parte de la jerarquía de +subdirectorios de config/ se copian estos ficheros. Se puede incluir cosas +como listas de paquetes personalizadas, imágenes gráficas personalizadas o +scripts gancho (hook scripts) para ejecutar o en el momento de creación de +la imagen o en el momento de arranque del sistema en vivo, aumentando la ya +por otra parte considerable flexibilidad de Debian Live con código creado ex +profeso. + +2~ Tareas de personalización + +Los siguientes capítulos se organizan por tareas de personalización que el +usuario realiza típicamente: Los capítulos de {Personalización de la +instalación de paquetes}#customizing-package-installation, {Personalización +de contenidos}#customizing-contents y {Personalización de las variantes +locales e idioma}#customizing-locale-and-language cubren solamente unas +pocas de las tareas que pueden realizarse. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-packages.ssi new file mode 100644 index 0000000..390d921 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-packages.ssi @@ -0,0 +1,704 @@ +:B~ Personalización de la instalación de paquetes + +1~customizing-package-installation Personalización de la instalación de +paquetes + +Quizás la tarea más básica de personalización de un sistema en vivo es la +selección de paquetes que serán incluidos en la imagen. Este capítulo +orienta a través de las diferentes opciones de live-build que, en el momento +de la creación de la imagen, personalizan la instalación de paquetes. Las +opciones que seleccionan la distribucion base y las áreas del archivo a +utilizar son las que más influyen a la hora de conocer qué paquetes estarán +disponibles para su instalación en la imagen. Para asegurar una buena +velocidad de descarga de paquetes, se debería elegir el repositorio más +cercano. Se pueden añadir repositorios para backports, experimentales, +paquetes personalizados o incluir ficheros de paquetes directamente. Se +pueden definir listas de paquetes personalizadas, incluyendo metapaquetes +que instalarán muchos paquetes relacionados, como por ejemplo paquetes de un +entorno de escritorio o lenguaje particular. Por último existen varias +opciones que dan algún control sobre cuando son instalados los paquetes por +la herramienta /{apt}/ o la herramienta /{aptitude}/, según sea la +elegida. Estas opciones pueden ser útiles si se utiliza un proxy, se quiere +desactivar la instalación de paquetes recomendados para ahorrar espacio o se +necesita controlar las versiones de los paquetes a instalar mediante APT +pinning, por nombrar algunas posibilidades. + +2~ Origen de los paquetes + +3~ Distribución, áreas de archivo y modo + +La distribución seleccionada tiene gran impacto en qué paquetes están +disponibles para incluir en la imagen. Se debe indicar el nombre en clave de +la distribución, que por defecto es ${testing} para la versión ${testing} de +live-build. Se puede especificar cualquier nombre de distribución disponible +en los repositorios indicando su nombre en clave. (Para más detalles ver +{Términos}#terms). La opción #{--distribution}# no solamente influencia la +fuente de los paquetes dentro del archivo, sino que instruye a live-build a +comportarse tal y como se necesita para construir cada una de las +distribuciones. Por ejemplo, para construir la versión *{inestable}*, sid, +se debe indicar: + +code{ + + $ lb config --distribution sid + +}code + +Las áreas del archivo Debian son la principal división de paquetes dentro de +una distribución dada. En Debian las áreas del archivo establecidas son +#{main}#, #{contrib}# y #{non-free}#. Solamente los paquetes contenidos en +#{main}# son parte de la distribución Debian. Ésta es el área definida por +defecto en live-build. Se pueden indicar uno o más valores tal y como se +muestra en el siguiente ejemplo: + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimentalmente se da soporte a alguna distribución derivada de Debian +mediante la opción #{--mode}#. Por defecto, esta opción toma el valor +#{debian}# sólo si se está construyendo en un sistema Debian o en un sistema +desconocido. Si se utiliza #{lb config}# en cualquiera de las distribuciones +derivadas a las que se da soporte, por defecto se construirá una imagen de +esa distribución derivada. Por ejemplo, si #{lb config}# se ejecuta en modo +#{ubuntu}# se utilizará el nombre de esa distribución y las áreas de +archivos específicas de esa distribución derivada en lugar de los propios de +Debian y live-build modificará su comportamiento para adecuarlo al modo +seleccionado. + +*{Nota:}* La ayuda a los usuarios de las distribuciones para las cuales se añadieron estos modos son responsabilidad de los desarrolladores de dichas distribuciones. El ${project} proporciona ayuda al desarrollo de la mejor manera posible, basándose en la información recogida de dichas distribuciones derivadas a pesar de que no desarrolla ni da soporte a las mismas. + +3~ Réplicas de Distribución Debian + +Los repositorios de Debian están replicados en una gran red alrededor del +mundo, de manera que se puede seleccionar la réplica más cercana con el fin +de obtener la mejor velocidad de descarga. Cada una de las opciones +#{--mirror-*}# gobierna qué réplica de repositorio Debian se utiliza en las +diferentes etapas de creación. Si se recuerda de {Etapas de la +creación}#stages-of-the-build, en la etapa *{bootstrap}* es cuando se crea +el directorio chroot con un sistema mínimo mediante la herramienta +/{debootstrap}/, y en la etapa *{chroot}* es cuando el directorio chroot es +completado con los paquetes necesarios para crear el sistema de ficheros que +será utilizado en el sistema en vivo. A cada una de estas etapas le +corresponde su propia opción #{--mirror-*}#. Posteriormente, en la etapa +*{binary}* se utilizarán las réplicas Debian indicadas en los valores de las +opciones #{--mirror-binary}# y #{--mirror-binary-security}# en lugar de +utilizar los indicados para las etapas anteriores. + +3~distribution-mirrors-build-time Réplicas de Distribution utilizadas +durante la creación + +Para indicar qué réplicas deben ser utilizadas en el momento de crear la +imagen es suficiente con utilizar las opciones #{--mirror-bootstrap}# y +#{--mirror-chroot-security}# como se muestra a continuación. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +El valor indicado en #{--mirror-chroot}# es utilizado como valor por defecto +para la opción #{--mirror-bootstrap}# si esta no es especificada. + +3~ Réplicas de distribución Debian utilizadas en la ejecución. + +Las opciones #{--mirror-binary*}# gobiernan las réplicas configuradas en la +imagen binaria que serán utilizadas para instalar paquetes adicionales +mientras se ejecuta el sistema en vivo. Por defecto se utiliza +#{httpredir.debian.org}#, que es un servicio que selecciona la réplica más +cercana basándose, entre otras cosas, en la familia de la IP del usuario y +de la disponibilidad de la réplica. Es una elección bastante acertada +siempre que no se pueda predecir que réplica será la mejor para todos los +usuarios. También se puede especificar valores personalizados como se +muestra en el siguiente ejemplo. Una imagen construida con esta +configuración solamente sería accesible a los usuarios de una red donde +"#{mirror}#" fuese alcanzable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Repositorios adicionales + +Se pueden añadir más repositorios, ampliando la lista de paquetes +seleccionables más alla de aquellos disponibles para la distribución +indicada, como pueden ser paquetes de backports, paquetes experimentales o +personalizados. Para configurar repositorios adicionales se debe crear los +ficheros #{config/archives/your-repository.list.chroot}# y/o +#{config/archives/your-repository.list.binary}#. Al igual que en las +opciones #{--mirror-*}#, estos ficheros gobiernan los repositorios +utilizados en las etapas *{chroot}* y *{binary}* respectivamente, esto es, +los repositorios que serán utilizados cuando se ejecute el sistema en vivo. + +Por ejemplo, #{config/archives/live.list.chroot}# permite instalar paquetes +de las instantáneas del repositorio Debian Live en el momento de crear la +imagen. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +Si se añade la misma línea a #{config/archives/live.list.binary}#, el +repositorio será añadido al directorio #{/etc/apt/sources.list.d/}# del +sistema en vivo. + +Estos ficheros serán seleccionados automáticamente si existen. + +Se debería también incluir en el fichero +#{config/archives/your-repository.key.{binary,chroot}}# la clave GPG a +utilizar para firmar dicho repositorio. + +En caso de necesitar un APT pinning personalizado, las preferencias de APT +se pueden colocar mediante ficheros +#{config/archives/your-repository.pref.{binary,chroot}}#, y serán añadidos +automáticamente al sistema en vivo en el directorio +#{/etc/apt/preferences.d/}#. + +2~choosing-packages-to-install Selección de los paquetes a instalar + +Hay varias maneras de seleccionar qué paquetes serán instalados por +live-build en la imagen que cubren una variedad de necesidades diversas. Se +puede nombrar paquetes individuales para instalar en una lista de +paquetes. También se puede utilizar metapaquetes en esas listas, o +selecionarlas utilizando campos de ficheros de control de paquetes. Por +último, también se pueden utilizar ficheros de paquetes de prueba o +experimentales obtenidos antes de que aparezcan en los repositorios +oficiales simplemente depositando estos ficheros directamente en el árbol de +directorios #{config/}#. + +3~package-lists Listas de paquetes + +Las listas de paquetes proporcionan una potente forma de expresar qué +paquetes deberían ser instalados. La sintaxis de las listas soporta las +expresiones condicionales, que facilitan la creación de listas, adaptando su +utilización a diversas configuraciones. También se pueden añadir nombre de +paquetes en la listas utilizando shell helpers en tiempo de construcción. + +*{Nota:}* El comportamiento de live-build cuando se especifica un paquete que no existe es determinado por lo que se haya configurado en la utilidad APT. Para más detalles ver {Utilizar apt o aptitude}#choosing-apt-or-aptitude. + +3~using-metapackages Utilizar metapaquetes + +La manera más sencilla de rellenar una lista de paquetes es utilizar una +tarea metapaquete mantenida por una distribución. Por ejemplo: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +Esto reemplaza el antiguo método de listas predefinidas compatible con +#{live-build}# 2.x. A diferencia de las listas predefinidas, los +metapaquetes de tareas no son específicos del proyecto Live Systems. Por el +contrario, son mantenidas por grupos de especialistas que trabajan en la +distribución y por lo tanto, reflejan el consenso de cada grupo acerca de +qué paquetes sirven mejor a las necesidades de los usuarios. Además, abarcan +una gama mucho más amplia de casos de uso que las listas predefinidas a las +que sustituyen. + +Todos los metapaquetes de tareas tienen el prefijo #{task-}#, por lo que +una forma rápida de determinar cuales están disponibles (aunque puede +contener un puñado de entradas falsas que coincidan con el nombre, pero que +no son metapaquetes) es buscar el nombre del paquete con: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +Además de éstos, se encuentran otros metapaquetes con diversos +fines. Algunos son subconjuntos de paquetes de tareas más amplias, como +#{gnome-core}#, mientras que otros son partes especializadas individuales de +un Debian Pure Blend, como los metapaquetes #{education-*}#. Para tener una +lista de todos los metapaquetes en el archivo, instalar el paquete +#{debtags}# y listar todos los paquetes con la etiqueta +#{role::metapackage}# de la siguiente manera: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Listas de paquetes locales + +Ya sea incluyendo metapaquetes en una lista, paquetes individuales, o una +combinación de ambos, todas las listas de paquetes locales se deben +almacenar en #{config/package-lists/}#. Ya que se puede utilizar más de una +lista, esto se presta muy bien a los diseños modulares. Por ejemplo, se +puede dedicar una lista a una elección particular de escritorio, la otra a +una colección de paquetes relacionados que puedan ser fácilmente utilizados +sobre un escritorio diferente. Esto permite experimentar con diferentes +combinaciones de conjuntos de paquetes con un mínimo esfuerzo, así como +compartir listas comunes entre diferentes proyectos de imágenes en vivo. + +Para que sean procesadas, las listas de paquetes que se depositen en este +directorio deben tener la extensión #{.list}# además de la extensión de la +etapa #{.chroot}# o #{.binary}# para indicar a qué etapa corresponde la +lista. + +*{Nota:}* Si no se especifica el sufijo, la lista será usada en las dos etapas. En consecuencia, es conveniente especificar #{.list.chroot}# de modo que los paquetes se instalen únicamente en el sistema en vivo y no exista otra copia extra del paquete #{.deb}#. + +3~ Listas de paquetes locales para la etapa binary + +Para crear una lista para la etapa «binary» crear un fichero con el sufijo +#{.list.binary}# en #{config/package-lists/}#. Estos paquetes no son +instalados en el sistema en vivo, pero son incluidos en #{pool/}#. El uso +típico de una de estas lista sería para una de las variantes de instalador +normal («non-live» N.del T.). Tal y como se mencionaba anteriormente, si se +desea usar la misma lista para la etapa «chroot» basta con solamente añadir +el sufijo #{.list}# + +3~generated-package-lists Generar listas de paquetes + +A veces ocurre que la mejor manera de crear una lista es generarla con un +script. Cualquier línea que comience con un signo de exclamación indica un +comando que se ejecutará dentro del chroot cuando la imagen se +construya. Por ejemplo, se podría incluir la línea #{! grep-aptavail -n +-sPackage -FPriority standard | sort}# en una lista de paquetes para +producir una lista ordenada de los paquetes disponibles con #{Priority: +standard}#. + +De hecho, la selección de paquetes con la orden #{grep-aptavail}# (del +paquete #{dctrl-tools}#) es tan útil que #{live-build}# proporciona un +script de ayuda llamado #{Packages}#. Este script acepta dos argumentos: +#{field}# y #{pattern}#. Por lo tanto, se puede crear una lista con los +siguientes contenidos: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Utilización de condiciones dentro de las listas de paquetes + +En las sentencias condicionales de las listas de paquetes pueden utilizarse +cualquier variable disponible en #{config/*}# (excepto las que tienen el +prefijo #{LB_}#). En general esto significa que puede utilizarse cualquier +opción válida para #{lb config}# cambiando las letras minúsculas por +mayúsculas y los guiones por barras bajas. En la práctica solamente tiene +sentido utilizar aquellas variables relacionadas con la selección de +paquetes, como pueden ser #{DISTRIBUTION}#, #{ARCHITECTURES}# o +#{ARCHIVE_AREAS}#. + +Por ejemplo, para instalar el paquete #{ia32-libs}# si se ha especificado la +arquitectura amd64 (#{--architectures amd64}#) se puede utilizar: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +En la expresión condicional pueden utilizarse varios valores. Por ejemplo +para instalar el paquete /{memtest86+}/ si la arquitectura es i386 +(#{--architectures i386}#) o es amd64 (#{--architectures amd64}#) se puede +especificar: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +En la expresión condicional también pueden utilizarse variables que pueden +contener más de un valor. Por ejemplo para instalar /{vrms}/ si se utilizan +las áreas del archivo #{contrib}# o #{non-free}# mediante la opción +#{--archive-areas}# se puede indicar: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +No se permite el anidamiento de estructuras condicionales. + +% FIXME: + +3~ Eliminación paquetes durante la instalación + +Se puede crear listas de paquetes en ficheros con los sufijos +#{.list.chroot_live}# y #{.list.chroot_install}# dentro del directorio +#{config/package-lists}#. Si existe una lista «live» y una lista «install» +los paquetes de la lista #{.list.chroot_live}# se eliminan con un script +gancho después de la instalación (si el usuario utiliza el instalador). Los +paquetes de la lista #{.list.chroot_install}# estarán presentes tanto en el +sistema en vivo como en el sistema instalado. Este es un caso especial para +el instalador y puede ser útil si se tiene #{--debian-installer live}# +establecido en la configuración y se desea eliminar paquetes específicos del +sistema en vivo durante la instalación. + +3~desktop-and-language-tasks Tareas de Escritorio e Idioma + +Las tareas de escritorio y de idioma son casos especiales que necesitan un +poco de planificación y configuración extra. Si el medio de instalación fue +preparado para una clase particular de entorno de escritorio, el Instalador +de Debian instalará automáticamente la tarea de entorno de escritorio +correspondiente. Para ello existen las tareas internas #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# y #{xfce-desktop}# pero ninguna de ellas +son presentadas en el menú de #{tasksel}#. De igual forma, las tareas para +idiomas tampoco son presentadas en el menú de #{tasksel}#, pero la selección +del idioma, al inicio de la instalación repercute en la selección de las +correspondientes tareas del idioma. + +Cuando se desarolla una imagen de escritorio, la imagen normalmente arranca +directamente a un escritorio de trabajo, las opciones de escritorio y de +idioma por defecto han sido elegidas en tiempo de creación, no en tiempo de +ejecución como en el caso del instalador de Debian. Eso no quiere decir que +una imagen en vivo no pueda ser creada para admitir múltiples escritorios o +varios idiomas y ofrecer al usuario una elección, pero ese no es un +comportamiento por defecto de live-build. + +Ya que no se ha previsto la instalación automática de tareas de idiomas, que +incluyen cosas tales como tipos de letra específicos de cada lengua o +paquetes de métodos de entrada, si se quiere incluirlos, es necesario +especificarlo en la configuración. Por ejemplo, una imagen de escritorio +GNOME que contenga soporte para el alemán podría incluir los siguientes +metapaquetes de tareas: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Versión y tipo de kernel + +Dependiendo de la arquitectura, se incluyen por defecto en las imágenes uno +o más tipos de kernels. Se puede elegir entre diferentes tipos utilizando la +opción #{--linux-flavours}#. Cada tipo tiene el sufijo de la raíz +predeterminada #{linux-image}# para formar el nombre de cada metapaquete que +a su vez depende del paquete del kernel exacto que debe incluirse en la +imagen. + +Así, por defecto, una imagen de arquitectura #{amd64}# incluirá el +metapaquete #{linux-image-amd64}# y una imagen de arquitectura #{i386}# +incluirá el metapaquete #{linux-image-586}#. + +Cuando hay más de una versión diferente del paquete del kernel disponible en +los archivos configurados, se puede especificar el nombre de un paquete del +kernel diferente con la opción #{--linux-packages}#. Por ejemplo, suponer +que se está construyendo una image de arquitectura #{amd64}# y se quiere +añadir el archivo experimental a fin de realizar pruebas. Para que se pueda +instalar el kernel #{linux-image-3.18.0-trunk-amd64}#, se podría configurar +la imagen de la siguiente manera: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Kernels personalizados + +Se pueden crear e incluir kernels personalizados, pero hay que tener en +cuenta que live-build sólo soporta los kernels que se integran en el sistema +de gestión de paquetes de Debian y no es compatible con kernels que no esten +en paquetes #{.deb}#. + +La manera apropiada y recomendada de implementar los propios paquetes del +kernel es seguir las instrucciones del #{kernel-handbook}#. Recordar +modificar el ABI y los sufijos de los tipos del kernel e incluir los +paquetes del kernel completo en un repositorio que coincidan con los +paquetes #{linux}# y #{linux-latest}#. + +Si se opta por construir los paquetes del kernel sin los metapaquetes +adecuados, es necesario especificar una raíz #{--linux-packages}# apropiada +como se indica en {Versión y tipo de kernel}#kernel-flavour-and-version. Tal +y como se explica en {Instalar paquetes modificados o de +terceros}#installing-modified-or-third-party-packages, es mejor si se +incluyen los paquetes del kernel personalizado en un repositorio propio, +aunque las alternativas discutidas en esa sección también funcionan. + +Está más allá del alcance de este documento dar consejos sobre cómo +personalizar un kernel. Sin embargo, se debe por lo menos, asegurarse de que +la configuración cumple los siguientes requisitos mínimos: + +_* Utilizar un ramdisk inicial. + +_* Incluir el módulo de unión de sistemas de ficheros (normalmente +#{aufs}#). + +_* Incluir todos los módulos de sistemas de ficheros requeridos por la +configuración (normalmente #{squashfs}#). + +2~installing-modified-or-third-party-packages Instalar paquetes modificados +o de terceros + +Si bien está en contra de la filosofía de un sistema en vivo, en ocasiones +es necesario crear un sistema con versiones de paquetes modificados a partir +de los disponibles en el repositorio de Debian. Estos paquetes pueden +modificar características existentes o dar soporte a características +adicionales, idiomas y marcas, o eliminar elementos existentes en los +paquetes que no son de interes. De manera similar, se pueden incluir +paquetes «de terceros» para añadir funcionalidades a medida o propietarias. + +En esta sección no se describe la creación o mantenimiento de paquetes +personalizados. Puede ser interesante una lectura del método descrito por +Joachim Breitner 'How to fork privately' en +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html. +La guía del nuevo desarrollador de Debian en +https://www.debian.org/doc/maint-guide/ describe la creación de paquetes a +medida. + +Existen dos formas de instalar paquetes personalizados: + +_* #{packages.chroot}# + +_* Utilizando un repositorio APT personalizado + +El método #{packages.chroot}# es el más simple para añadir paquetes +personalizados. Es muy útil para personalizaciones «rápidas» pero tiene unos +cuantos inconvenientes mientras que la utilización de un repositorio APT +personalizado es más lento de poner en marcha. + +3~ Método #{packages.chroot}# para instalar paquetes personalizados + +Para instalar paquetes personalizados solamente hay que copiar el paquete en +el directorio #{config/packages.chroot/}#. Los paquetes contenidos en este +directorio serán automáticamente instalados en el sistema en vivo durante el +proceso de creación. No es necesario especificar nada más. + +Los paquetes *{deben}* nombrarse de la forma prescrita. La forma más simple +es usar #{dpkg-name}#. + +El método #{packages.chroot}# para la instalación de paquetes personalizados +tiene desventajas: + +_* No es posible utilizar secure APT. + +_* Se deben depositar todos los paquetes apropiados en el directorio +#{config/packages.chroot/}#. + +_* No es adecuado para almacenar configuraciones en vivo en un control de +versiones. + +3~ Método de repositorio APT para instalar paquetes personalizados + +A diferencia del método #{packages.chroot}#, cuando se utiliza el método de +repositorio APT personalizado se debe asegurar que se especifica dónde se +deben buscar los paquetes a instalar. Para más información ver {Selección de +los paquetes a instalar}#choosing-packages-to-install. + +Aunque crear un repositorio APT para instalar paquetes personalizados puede +parecer un esfuerzo innecesaro, la infraestructurar puede ser fácilmente +reutilizada posteriormente para ofrecer nuevas versiones de los paquetes. + +3~ Paquetes personalizados y APT + +live-build utiliza APT para instalar todos los paquetes en el sistema en +vivo, así que hereda sus comportamientos. Un punto a resaltar es que +(asumiendo una configuración de APT por defecto) dado un paquete en dos +repositorios diferentes con diferentes números de versiones, APT +seleccionará para instalar el paquete con número de versión superior. + +Esta sería una buena razón para incrementar el número de version en los +ficheros #{debian/changelog}# de los paquetes personalizados y así asegurar +que serán estos los paquetes instalados en lugar de los contenidos en los +repositorios oficiales de Debian. Esto puede también lograrse alterando las +preferencias de pinning de APT del sistema en vivo. Para más información ver +{APT pinning}#apt-pinning. + +2~ Configurar APT en la creación + +Se puede configurar APT mediante varias opciones que se aplicarán en el +momento de crear la imagen. (La configuración que APT utilizará cuando se +ejecute el sistema en vivo puede ser configurada de la manera que +habitualmente se utiliza para introducir contenidos del sistema en vivo, +esto es, incluyendo las configuraciones apropiadas en el directorio +#{config/includes.chroot/}#.) Se puede encontrar una lista completa de las +opciones para configurar APT en la página de manual de #{lb_config}#. Son +aquellas opciones que comienzan con #{apt}#. + +3~choosing-apt-or-aptitude Utilizar apt o aptitude + +Se puede seleccionar qué herramienta se utilizará para instalar paquetes, +/{apt}/ o /{aptitude}/, en el momento de crear la imagen mediante la opción +#{--apt}# de #{lb config}#. Esta selección definirá el comportamiento +preferido en la instalación de paquetes, siendo la mayor diferencia la +manera de tratar los paquetes no disponibles. + +_* #{apt}#: Con este método, si se especifica un paquete no existente, la +instalación fallará. Es el comportamiento por defecto. + +_* #{aptitude}#: Con este método, si se especifica un paquete no existente, +la instalación continuará sin error. + +3~ Utilización de un proxy con APT + +Un problema habitual en la configuración de APT es tratar con la creación de +una imagen desde detras de un proxy. Se puede especificar dicho proxy con +las opciones #{--apt-ftp-proxy}# o #{--apt-http-proxy}#. Por ejemplo: + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Ajuste de APT para ahorrar espacio + +En ocasiones es necesario ahorrar un poco de espacio en el medio de +instalación. Las dos opciones descritas a continuación pueden ser de +interes. + +Si no se desea incluir los índices de APT en la imagen creada se puede +utilizar la siguiente opción: + +code{ + + $ lb config --apt-indices false + +}code + +Esto no modificará el comportamiento de las entradas definidas en +#{/etc/apt/sources.list}#, sino que solo afecta a si exitirán o no ficheros +de índice en el directorio #{/var/lib/apt}#. El compromiso viene de que APT +necesita estos ficheros índices para funcionar en el sistema en vivo, así +que, si no existen, el usuario deberá ejecutar la orden #{apt-get update}# +para crear estos índices antes de poder ejecutar una orden del tipo +#{apt-cache search}# o #{apt-get install}#. + +Si la instalación de los paquetes recomendados aumenta demasiado el tamaño +de la imagen, siempre y cuando se esté preparado para hacer frente a las +consecuencias que se mencionan a continuación, se puede desactivar el valor +por defecto de esta opción de APT con: + +code{ + + $ lb config --apt-recommends false + +}code + +La consecuencia más importante de desactivar los «recommends» es que +#{live-boot}# y #{live-config}# recomiendan algunos paquetes que +proporcionan una funcionalidad importante y que son utilizados por la +mayoría de las configuraciones en vivo, como por ejemplo #{user-setup}# +recomendado por #{live-config}# que se utiliza para crear el usuario en +vivo. En todas menos en las circunstancias más excepcionales es necesario +volver a añadir por lo menos algunos de los «recommends» en las listas de +paquetes o de lo contrario la imagen no funcionará como se espera, si es que +funciona en lo más minimo. Mirar los paquetes recomendados por cada uno de +los paquetes #{live-*}# incluidos en la construcción y si no se está seguro +de que es lo que se puede omitir, volver a agregarlo utilizando las listas +de paquetes. + +La consecuencia más general es que, si no se instalan los paquetes +recomendados para un paquete dado, esto es «los paquetes que supuestamente +deberían encontrase intalados si un paquete ya lo está» (Debian Policy +Manual, seccion 7.2), algún paquete que supuestamente debería estar +instalado será omitido. Por lo tanto, se sugiere que si se desactiva esta +opción, se revise las diferencias en las listas de paquetes instalados (ver +el fichero #{binary.packages}# generado por #{lb build}#) y que se vuelva a +incluir en la lista cualquier paquete que deba ser instalado. Si se +considera que el número de paquetes a descartar es pequeño, se recomienda +que la opción se deje activada y que se utilice una prioridad pin negativa +de APT en dichos paquetes y así evitar que sean instalados tal y como se +explica en {APT pinning}#apt-pinning. + +3~ Pasar opciones a apt o a aptitude + +Si no hay una opción #{lb config}# para modificar el comportamiento de APT +en la forma que se necesita, utilizar #{--apt-options}# o +#{--aptitude-options}# para pasar opciones a la herramienta APT +configurada. Consultar las páginas de manual #{apt}# y #{aptitude}# para más +detalles. Tener en cuenta que ambas opciones tienen valores por defecto que +tendran que mantenerse, además de las opciones que se pueden +especificar. Así, por ejemplo, supongamos que se ha incluido algo con fines +de prueba de #{snapshot.debian.org}# y se desea especificar +#{Acquire::Check-Valid-Until=false}# para que APT esté feliz con el fichero +#{Release}# caducado, se haría como en el ejemplo siguiente, añadiendo la +opción de nuevo después del valor por defecto #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Consultar las páginas de manual para entender completamente estas opciones y +cuándo utilizarlas. Esto es sólo un ejemplo y no debe ser interpretado como +consejo para configurar la imagen. Esta opción no sería apropiada para, por +ejemplo, una versión final de una imagen en vivo. + +Para configuraciones más complicadas que implican opciones #{apt.conf}# +puede ser necesario crear un fichero #{config/apt/apt.conf}#. Ver tambien +las otras opciones #{apt-*}# para tener algunos atajos convenientes para las +opciones que se necesitan con frecuencia. + +3~apt-pinning APT pinning + +Como información básica, sería recomendable leer la página de manual +#{apt_preferences(5)}#. APT pinning puede ser configurado o en tiempo de +creación de la imagen, creando los ficheros #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, y #{config/apt/preferences}#. o en tiempo +de ejecución del sistema en vivo creando el fichero +#{config/includes.chroot/etc/apt/preferences}#. + +Supongamos que se está creando un sistema en vivo basado en ${testing} pero +se necesita instalar todos los paquetes "live" que terminan instalados en la +imagen binaria final desde la versión inestable «sid» en el momento de crear +la imagen. Se deberá añadir sid a los orígenes (sources) de APT y fijar +(pin) los paquetes live con una prioridad más alta pero todos los otros +paquetes con una prioridad más baja que la prioridad por defecto de manera +que solamente los paquetes fijados sean instalados desde sid mientras que el +resto será obtenido desde la distribución base, ${testing}. Esto se puede +realizar de la siguiente forma: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Una prioridad pin negativa previene la instalación de un paquete, como puede +ser el caso de que no se desee que un paquete recomendado por otro sea +instalado al instalar el primero. Supongamos que se está creando una imagen +LXDE añadiendo #{task-lxde-desktop}# en +#{config/package-lists/desktop.list.chroot}#, pero no se desea preguntar al +usuario si desea almacenar las claves wifi en el keyring. Este metapaquete +depende de /{lxde-core}/, el cual recomienda /{gksu}/ que a su vez +recomienda /{gnome-keyring}/. Así que el objetivo es omitir la instalación +del paquete /{gnome-keyring}/, que puede conseguirse añadiendo un fichero +con el siguiente contenido a #{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-runtime.ssi new file mode 100644 index 0000000..2a89991 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_customization-runtime.ssi @@ -0,0 +1,477 @@ +:B~ Personalización del comportamiento en tiempo de ejecución. + +1~customizing-run-time-behaviours Personalización del comportamiento en +tiempo de ejecución. + +Toda la configuración que se hace en tiempo de ejecución es realizada por +live-config. Éstas son algunas de las opciones más comunes de live-config en +las que los usuarios están más interesados. Se puede encontrar una lista +completa de todas las posibilidades en la página de manual de live-config. + +2~ Personalización del usuario por defecto del sistema en vivo + +Una consideración importante es que el usuario por defecto del sistema en +vivo es creado por live-boot en el arranque y no live-build durante la +creación de la imagen. Ésto no sólo influye dónde se introducen los +materiales relacionados con este usuario durante la creación de la imagen +tal y como se explica en {Includes locales en +Live/chroot}#live-chroot-local-includes sino también a cualquier grupo y a +los permisos asociados con el usuario por defecto del sistema en vivo. + +Se pueden especificar grupos adicionales a los que pertenecerá el usuario +por defecto del sistema en vivo mediante el uso de cualquiera de las +posibilidades de configuración de live-config. Por ejemplo, para agregar el +usuario al grupo #{fuse}#, se puede agregar el fichero siguiente a +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +o utilizar +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +como parámetro de arranque. + +Además, es posible cambiar el usuario por defecto "user" y la contraseña por +defecto "live". Si se desea cambiarlos por cualquier motivo, se puede +conseguir de forma sencilla tal y como se explica a continuación: + +Cambiar el nombre del usuario por defecto es tan sencillo como especificarlo +en la configuración: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +Una posible forma de cambiar la contraseña por defecto es usando un script +gancho (hook) tal y como se describe en {Scripts gancho en tiempo de +arranque}#boot-time-hooks. Para conseguirlo se puede usar el script gancho +«passwd» de #{/usr/share/doc/live-config/examples/hooks}#, ponerle un +prefijo adecuado (p.ej. 2000-passwd) y añadirlo a +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Personalización de las variantes locales e +idioma + +Cuando el sistema en vivo arranca, el idioma está implicado en dos pasos: + +_* Generar las variantes locales + +_* Establecer la distribución del teclado + +La variante local predeterminada en la creación de un sistema en vivo es +#{locales=en_US.UTF-8}#. Para definir la variante local que se debe generar, +se puede utilizar el parámetro #{locales}# en la opción +#{--bootappend-live}# de #{lb config}#, p.ej. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Se pueden especificar diversas variantes locales separándolas con comas. + +Este parámetro se puede utilizar en la línea de comandos del kernel, al +igual que los parámetros de configuración del teclado indicados a +continuación. Es posibe configurar una variante local con #{idioma_país}# +(en cuyo caso se utiliza el tipo de codificación por omisión) o también con +la expresión completa #{idioma_país.codificación}#. La lista de todas las +variantes locales está en #{/usr/share/i18n/SUPPORTED}#. + +#{live-config}# se encarga de la configuración del teclado de la consola y +del entorno gráfico X utilizando el paquete #{console-setup}#. Para +configurarlos se puede utilizar los parámetros de arranque +#{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# y +#{keyboard-model}# a través de la opción #{--bootappend-live}#. Se puede +encontrar una lista de opciones válidas para estos parámetros en +#{/usr/share/X11/xkb/rules/base.lst}#. Para hallar la distribución del +teclado y la variante que corresponde a un idioma se puede buscar el nombre +en inglés de la nación donde se habla el idioma, por ejemplo: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Cada variante muestra una descripción de la disposición que aplica. + +Normalmente, sólo es necesario configurar la disposición del teclado. Por +ejemplo, para obtener los ficheros de la variante local de la disposición +del teclado alemán y suizo-alemán en X utilizar: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +Sin enbargo, para casos de uso muy específicos, se puede incluir otros +parámetros. Por ejemplo, para configurar un sistema Francés con una +disposición French-Dvorak (también llamado Bepo) en un teclado USB +TypeMatrix EZ-Reach 2030, utilizar: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Para cada una de las variables de configuración del teclado #{keyboard-*}# +se puede especificar varios valores separados por comas. A excepción de +#{keyboard-model}#, que sólo acepta un valor. En la página de manual +#{keyboard(5)}# se explican los detalles y algunos ejemplos de cómo utilizar +las variables #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# y +#{XKBOPTIONS}#. Si se especifican diferentes valores en +#{keyboard-variants}# estos se corresponderan uno a uno con los valores +#{keyboard-layouts}# (ver #{setxkbmap(1)}# opción #{-variant}#). Se admiten +valores vacíos; por ejemplo para definir dos distribuciones de teclado, la +que se usa por omisión US QWERTY y otra US Dvorak, utilizar: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistencia + +Un paradigma de un cd en vivo («live cd» N. del T.) es ser un sistema +pre-instalado que funciona desde medios de almacenamiento de sólo lectura, +como un CD-ROM, donde los cambios y las modificaciones no se guardan tras +reiniciar el sistema en que se ejecuta. + +Un sistema en vivo es una generalización de este paradigma pero que es +compatible con otros medios de almacenamiento, no sólo en CDs. Aún así, en +su comportamiento predeterminado, se debe considerar un sistema de sólo +lectura y todos los cambios en tiempo de ejecución del sistema se pierden al +apagar el equipo. + +La «persistencia» es un nombre común que se da a los diferentes tipos de +soluciones para guardar algunos o todos los cambios realizados durante la +ejecución tras reiniciar el sistema. Para entender cómo funciona es útil +saber que incluso si el sistema se inicia y se ejecuta desde los medios de +almacenamiento de sólo lectura, las modificaciones de los ficheros y +directorios se escriben en medios de escritura, por lo general en la memoria +ram (tmpfs) y los datos guardados en la ram se pierden al reiniciar. + +Los datos almacenados en esta memoria ram se pueden guardar en un soporte +grabable, como un medio de almacenamiento local, un recurso compartido en +red o incluso en una sesión de un CD/DVD regrabable en multisesión. Todos +estos medios son compatibles de diferentes maneras y todos, menos el último, +requieren un parámetro de arranque especial que se especificará en el +momento del arranque: #{persistence}#. + +Si se usa el parámetro de arranque #{persistence}# (y no se usa la opción +#{nopersistence}#), se busca en los medios de almacenamiento locales +(p.ej. discos duros, llaves USB) volúmenes con persistencia durante el +arranque. Es posible restringir qué tipos de volúmenes persistentes se +pueden usar especificando ciertos parámetros de arranque descritos en la +página del manual de live-boot(7). Un volumen persistente es cualquiera de +los siguientes: + +_* una partición, identificada por su nombre GPT. + +_* Un sistema de ficheros, identificado por su etiqueta de sistema de +ficheros. + +_* una fichero imagen situado en la raíz de cualquier sistema de ficheros +que pueda ser leido (incluso una partición NTFS de otro sistema operativo), +identificado por su nombre de fichero. + +La etiqueta del volumen para las overlays debe ser #{persistence}# pero será +ignorado a menos que contenga en su raíz un fichero llamado +#{persistence.conf}# que se utiliza para personalizar la persistencia del +volumen, esto es, especificar los directorios que se desea guardar en un +volumen de persistencia después de reiniciar. Ver {El fichero +persistence.conf}#persistence-conf para más detalles. + +He aquí algunos ejemplos de cómo preparar un volumen para ser usado para la +persistencia. Puede ser, por ejemplo, una partición en un disco duro o en +una llave usb creada con, p.ej. + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +Ver {Usar el espacio libre en el dispositivo USB}#using-usb-extra-space. + +Si ya existe una partición en el dispositivo, sólo se tiene que cambiar la +etiqueta con uno de los siguientes: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Un ejemplo de cómo crear un fichero imagen basado en ext4 para ser usado +para la persistencia: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Después de crear el fichero imagen, a modo de ejemplo, para hacer #{/usr}# +persistente pero únicamente guardando los cambios que se realizan en ese +directorio en lugar de todos los contenidos de #{/usr}#, se puede utilizar +la opción "union". Si el fichero imagen se encuentra en el directorio home, +copiarlo a la raíz del sistema de ficheros del disco duro y montarlo en +#{/mnt}# como se explica a continuación: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Después, crear el fichero #{persistence.conf}# añadiendo contenido y +desmontar el fichero imagen. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Ahora, reiniciar y arrancar el medio en vivo con el parámetro de arranque +"persistence". + +3~persistence-conf El fichero persistence.conf + +Un volumen con la etiqueta #{persistence}# debe ser configurado a través de +un fichero #{persistence.conf}# para crear directorios arbitrarios +persistentes. Ese fichero, situado en el sistema de ficheros raíz del +volumen, controla que directorios hace persistentes y también de que manera. + +En la página de manual de persistence.conf(5) se explica en detalle cómo se +configura el montaje de las overlays, pero un sencillo ejemplo es suficiente +para la mayoría de los casos. Supongamos que queremos crear nuestro +directorio home y APT cache persistentes en un sistema de ficheros ext4 en +la partición /dev/sdb1: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Entonces reiniciamos. Durante el primer arranque los contenidos de #{/home}# +y #{/var/cache/apt}# se copiarán en el volumen persistente y a partir de ese +momento todos los cambios en esos directorios se guardarán allí. Tener en +cuenta que las rutas listadas en el fichero #{persistence.conf}# no pueden +contener espacios en blanco ni los componentes especiales #{.}# y +#{..}#. Además, ni #{/lib}#, #{/lib/live}# (o ninguno de sus +sub-directorios) ni #{/}# pueden hacerse persistentes montándolos de forma +personalizada. Una posible alternativa a esta limitación es añadir #{/ +union}# al fichero #{persistence.conf}# para conseguir una persistencia +completa. + +3~ Utilizar varios medios persistentes + +Existen diferentes métodos para utilizar múltiples volúmenes de persistencia +para diferentes casos de uso. Por ejemplo, utilizar varios volúmenes al +mismo tiempo o seleccionar sólo uno, entre varios, para fines muy +específicos. + +Se puede usar diferentes volúmenes de overlays al mismo tiempo (con sus +propios ficheros #{persistence.conf}#) pero si varios volúmenes hacen que un +mismo directorio sea persistente, sólo uno de ellos será usado. Si dos +unidades montadas están "anidadas" (es decir, una es un sub-directorio de la +otra) el directorio superior será montado antes que el inferior de este modo +no quedará uno escondido por el otro. La personalización de los montajes +anidadados es problemática si están listados en el mismo fichero +#{persistence.conf}#. Consultar la página de manual de persistence.conf(5) +para ver como manejar ese caso si realmente es necesario. (aclaración: +normalmente no lo es). + +Un posible caso de uso: Si se desea guardar los datos del usuario, es decir +#{/home}# y los datos del superusuario, es decir #{/root}# en particiones +diferentes, crear dos particiones con la etiqueta #{persistence}# y añadir +un fichero #{persistence.conf}# en cada una de este modo, #{# echo "/home" > +persistence.conf}# para la primera partición que guardará los ficheros del +usuario y #{# echo "/root" > persistence.conf}# para la segunda partición +que almacenará los ficheros del superusuario. Finalmente, utilizar el +parámetro de arranque #{persistence}#. + +Si un usuario necesita un almacenamiento persistente múltiple del mismo tipo +para diferentes lugares o pruebas, tales como #{private}# y #{work}#, el +parámetro de arranque #{persistence-label}# usado junto con el parámetro de +arranque #{persistence}# permitirá medios de almacenamiento persistentes +múltiples pero únicos. Un ejemplo sería, si un usuario desea utilizar una +partición persistente etiquetada #{private}# para datos de uso personal como +los marcadores de un navegador o similares utilizaría los parámetros de +arranque: #{persistence}# #{persistence-label=private}#. Y para almacenar +datos relacionados con el trabajo, como documentos, proyectos de +investigación o de otro tipo, utilizaría los parámetros de arranque: +#{persistence}# #{persistence-label=work}#. + +Es importante recordar que cada uno de estos volúmenes, #{private}# y +#{work}#, necesita también un fichero #{persistence.conf}# en su raíz. La +página de manual de live-boot contiene más información acerca de cómo +utilizar estas etiquetas con los antiguos nombres que se utilizaban en +anteriores versiones. + +3~ Utilizar persistencia con cifrado + +Utilizar la persistencia significa que algunos datos sensibles pueden estar +expuestos a riesgo. Especialmente si los datos persistentes se almacenan en +un dispositivo portable, como una memoria USB o un disco duro externo. Es +entonces cuando el cifrado cobra sentido. Incluso aunque todo el +procedimiento puede parecer complicado debido a la cantidad de pasos que hay +que hacer, es muy fácil manejar particiones cifradas con live-boot. Para +utilizar *{luks}*, que es el tipo de cifrado soportado, se necesita instalar +/{cryptsetup}/ tanto en la máquina que va a crear la partición cifrada como +en el sistema en vivo con que se va a utilizar la partición persistente +cifrada. + +Para instalar /{cryptsetup}/ en nuestra máquina: + +code{ + + # apt-get install cryptsetup + +}code + +Para instalar /{cryptsetup}/ en nuestro sistema en vivo, lo añadimos a una +package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Una vez se tiene el sistema en vivo con /{cryptsetup}/, básicamente, sólo se +necesita crear una nueva partición, cifrarla y arrancar con los parámetros +#{persistence}# y #{persistence-encryption=luks}#. Podríamos habernos +anticipado a este paso y haber añadido esos parámetros de arranque siguiendo +el procedimiento habitual: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Vamos a entrar en detalles para quien que no esté familiarizado con el +cifrado. En el siguiente ejemplo vamos a utilizar una partición en un +dispositivo usb que corresponde a #{/dev/sdc2}#. Tener en cuenta que es +necesario determinar qué partición es la que se va a utilizar en cada caso +específico. + +El primer paso es conectar la memoria usb y determinar de qué dispositivo se +trata. El método recomendado para los dispositivos en live-manual es +utilizando #{ls -l /dev/disk/by-id}#. Después de eso, crear una nueva +partición y, a continuación, cifrarla con una frase de contraseña de la +siguiente manera: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +A continuación, abrir la partición luks en el mapeador de dispositivos +virtuales. Se puede utilizar cualquier nombre que se desee. Aquí utilizamos +*{live}* como ejemplo: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +El siguiente paso es llenar el dispositivo con ceros antes de crear el +sistema de ficheros: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Ahora, estamos listos para crear el sistema de ficheros. Nótese que estamos +añadiendo la etiqueta #{persistence}# para que el dispositivo se monte como +almacén de persistencia durante el arranque. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +Para continuar con nuestra configuración, necesitamos montar el dispositivo, +por ejemplo, en #{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +Y crear el fichero #{persistence.conf}# en la raíz de la partición. Esto es, +como se ha explicado antes, estrictamente necesario. Ver {El fichero +persistence.conf}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Entonces, desmontar el punto de montaje: + +code{ + + # umount /mnt + +}code + +Y opcionalmente, aunque puede ser una buena manera de salvaguardar los datos +que acabamos de agregar a la partición, podemos cerrar el dispositivo: + +code{ + + # cryptsetup luksClose live + +}code + +Vamos a resumir el proceso. Hasta ahora, hemos creado un sistema vivo capaz +de utilizar el cifrado, que se puede copiar en una memoria usb como se +explica en {Copiar una imagen ISO híbrida en un dispositivo +USB}#copying-iso-hybrid-to-usb. También hemos creado una partición cifrada, +que se puede crear en la misma memoria usb para llevarla a todas partes y +hemos configurado la partición cifrada para ser utilizada como almacén de +persistencia. Así que ahora, sólo tenemos que arrancar el sistema en +vivo. En el momento del arranque, live-boot nos preguntará la frase de +contraseña y montará la partición cifrada para ser utilizada para la +persistencia. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_installation.ssi new file mode 100644 index 0000000..9da15fa --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_installation.ssi @@ -0,0 +1,183 @@ +:B~ Instalación + +1~installation Instalación + +2~requirements Requisitos + +Para crear las imágenes en vivo son necesarios los siguientes requisitos: + +_* Acceso de superusuario (root) + +_* Una versión actualizada de live-build + +_* Un intérprete de comandos compatible con POSIX, como por ejemplo /{bash}/ +o /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6.x o superior. + +Tener en cuenta que no es necesario el uso de Debian o una distribución +derivada de Debian - live-build funcionará en casi cualquier distribución +que cumpla con los requisitos anteriores. + +2~installing-live-build Instalación de live-build + +Se puede instalar live-build de varias maneras diferentes: + +_* Desde el repositorio Debian + +_* A partir del código fuente + +_* Usando instantáneas + +Si se usa Debian, el método recomendado es instalar live-build a través del +repositorio de Debian. + +3~ Desde el repositorio Debian. + +Simplemente instalar live-build como cualquier otro paquete: + +code{ + + # apt-get install live-build + +}code + +3~ A partir del código fuente + +live-build se desarrolla utilizando el sistema de control de versiones Git. +En los sistemas basados en Debian se encuentra el paquete /{git}/. Para ver +el último código, ejecutar: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +Se puede crear e instalar el paquete Debian ejecutando: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Si se desea, se podrá instalar cualquiera de los paquetes #{.deb}# recien +creados con el procedimiento anterior, p.ej. + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +También se puede instalar live-build directamente en el sistema ejecutando: + +code{ + + # make install + +}code + +y desinstalarlo con: + +code{ + + # make uninstall + +}code + +3~ A partir de «instantáneas» + +Si no se desea crear o instalar live-build a partir del código fuente, se +puede usar instantáneas. Estas se generan automáticamente a partir de la +última versión de Git y están disponibles en +http://live-systems.org/debian/. + +2~ Instalación de live-boot y live-config + +*{Nota:}* No es necesario instalar live-boot o live-config en el sistema para crear sistemas personalizados en vivo. Sin embargo, eso no causará ningún daño y es útil por motivos de referencia. Si únicamente se desea tener la documentación, es posible instalar los paquetes /{live-boot-doc}/ y /{live-config-doc}/ de forma independiente. + +3~ Desde el repositorio Debian. + +Tanto live-boot como live-config están disponibles en el repositorio Debian +siguiendo un procedimiento similar al explicado en la {Instalación de +live-build}#installing-live-build. + +3~ A partir del código fuente + +Para utilizar el último código fuente a partir de git, se puede seguir el +proceso siguiente. Asegurarse de estar familiarizado con los términos +mencionados en {Términos}#terms. + +_* Comprobar el código fuente de live-boot y live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Si se desea generar estos paquetes a partir del código fuente, se puede +consultar las páginas del manual para más detalles sobre la personalización +de live-boot y live-config. + +_* Creación de los paquetes .deb de live-boot y live-config + +Se debe crear ya sea en la distribución de destino o en un entorno chroot +que contenga la plataforma de destino: es decir, si el objetivo es +${testing} entonces se debe crear usando ${testing}. + +Utilizar un programa creador personal como /{pbuilder}/ o /{sbuild}/ si se +necesita crear live-boot para una distribución de destino diferente del +sistema de creación. Por ejemplo, para las imágenes en vivo de ${testing}, +crear live-boot en un entorno chroot ${testing}. Si la distribución de +destino coincide con la distribución actual, se puede crear directamente +sobre el sistema de creación con #{dpkg-buildpackage}# (proporcionada por el +paquete /{dpkg-dev}/ ): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Utilizar los ficheros .deb generados que proceda + +Como live-boot y live-config son instalados por el sistema de construcción +live-build, la instalación de esos paquetes en el sistema anfitrión no es +suficiente: se debe tratar los .deb generados como si fueran paquetes +personalizados. Puesto que el propósito de la construcción de estos paquetes +a partir del código fuente es probar cosas nuevas a corto plazo antes de su +lanzamiento oficial, seguir las instrucciones de {Instalar paquetes +modificados o de terceros}#installing-modified-or-third-party-packages para +incluir temporalmente los ficheros necesarios en la configuración. En +particular, observar que ambos paquetes se dividen en una parte genérica, +una parte de documentación y uno o más back-ends. Incluir la parte genérica, +sólo uno de los back-ends que coincida con la configuración y opcionalmente, +la documentación. Suponiendo que se está construyendo una imagen en vivo en +el directorio actual y se han generado todos los .deb para una única versión +de los dos paquetes en el directorio superior, estos comandos bash copiaran +todos los paquetes necesarios, incluyendo sus back-ends por defecto: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ A partir de «instantáneas» + +Se puede dejar que live-build utilice automáticamente las últimas +instantáneas de live-boot y live-config mediante la configuración del +repositorio de terceros live-systems.org en el directorio de configuración +de live-build. diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_managing_a_configuration.ssi new file mode 100644 index 0000000..b61bbab --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_managing_a_configuration.ssi @@ -0,0 +1,142 @@ +:B~ Gestionar una configuración + +1~managing-a-configuration Gestionar una configuración + +Este capítulo explica como gestionar una configuración para crear un sistema +en vivo desde el principio, pasando por sucesivas versiones tanto de la +herramienta live-build como de la imagen del sistema en vivo propiamente +dicha. + +2~ Gestionar cambios en la configuración + +Las configuraciones en vivo rara vez son perfectas al primer intento. Puede +estar bien pasar opciones a #{lb config}# en la línea de comandos para +realizar una construcción única, pero es más típico revisar esas opciones y +construir de nuevo hasta quedar satisfecho. Para gestionar estos cambios, se +pueden utilizar scripts auto que garanticen que la configuración se mantiene +en un estado coherente. + +3~ ¿Por qué utilizar scripts auto? ¿Qué hacen? + +El comando #{lb config}# almacena las opciones que se le pasan en ficheros +en el directorio #{config/*}#, junto con muchas otras opciones que figuran +en sus valores predeterminados. Si se ejecuta #{lb config}# una vez más, no +restablecerá ninguna opción que se estableció como por defecto en función de +las opciones iniciales. Así, por ejemplo, si se ejecuta #{lb config}# otra +vez con un nuevo valor para #{--binary-images}#, todas las opciones que se +establecieron como predeterminadas según la opción anterior ya no pueden +funcionar con la nueva. Estos ficheros tampoco estan destinados a ser leídos +o editados. Almacenan valores para más de cien opciones, y nadie es capaz de +ver las opciones que se especificó realmente. Y por último, si se ejecuta +#{lb config}# y a continuación se actualiza live-build y hay alguna opción +que cambió de nombre, #{config/*}# todavía tendrá variables con las opciones +viejas que ya no son válidas. + +Por todas estas razones, los scripts #{auto/*}# nos hacen la vida más +fácil. Son simples envoltorios para los comandos #{lb config}#, #{lb build}# +y #{lb clean}# diseñados para ayudar a gestionar una configuración. El +script #{auto/config}# contiene el comando #{lb config}# con todas las +opciones que se desea, el script #{auto/clean}# elimina los ficheros que +contienen variables de configuración y el fichero #{auto/build}# crea un +#{build.log}# de cada creación. Cada uno de estos scripts se ejecuta +automáticamente cada vez que se ejecuta la orden #{lb}# +correspondiente. Mediante el uso de estos scripts, la configuración es más +fácil de leer y se mantiene internamente coherente de una revisión a la +siguiente. Además, será mucho más fácil identificar y corregir las opciones +que necesitan cambiarse tras actualizar live-build y leer la documentación +actualizada. + +3~ Usar scripts auto de ejemplo + +Para mayor comodidad, live-build incluye scripts auto de ejemplo que se +pueden copiar y editar. Iniciar una nueva configuración por defecto y a +continuación, copiar los ejemplos: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Editar #{auto/config}#, añadiendo las opciones que se desee. Por ejemplo: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Ahora, cada vez que se utilize #{lb config}#, #{auto/config}# reiniciará la +configuración basándose en estas opciones. Cuando se desee realizar cambios, +se deben editar las opciones en este fichero en lugar de pasarlas a #{lb +config}#. Cuando se utilize #{lb clean}#, #{auto/clean}# limpiará los +ficheros en #{config/*}# junto a los otros productos de construcción. Y, por +último, cuando se utilice #{lb build}#, #{auto/build}# creará un log del +proceso de construcción llamado #{build.log}#. + +*{Nota:}* Aquí se utiliza #{noauto}#, un parámetro especial para suprimir otra llamada a #{auto/config}#, evitando así una repetición infinita. Asegurarse de no eliminarlo accidentalmente al hacer cambios en el fichero. Tener cuidado al dividir el comando #{lb config}# en varias líneas para facilitar la lectura, como se muestra en el ejemplo anterior, ya que no debe olvidarse la barra invertida (\) al final de cada línea que sigue en la siguiente. + +2~clone-configuration-via-git Clonar una configuración publicada a través de +Git + +Utilizar la opción #{lb config --config}# para clonar un repositorio Git que +contenga una configuración de un sistema en vivo. Si se desea basar la +configuración en una mantenida por el ${project}, visitar el repositorio en +http://live-systems.org/gitweb/ con el nombre #{live-images}# bajo el título +#{Packages}#. Este repositorio contiene las configuraciones que se utilizan +para las {imágenes prefabricadas}#downloading-prebuilt-images + +Por ejemplo, para construir una imagen standard, utilizar el repositorio +#{live-images}# de la siguiente manera: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Editar #{auto/config}# y cualquier otra cosa que se necesite en el árbol +#{config}# para adaptarlo a las propias necesidades. Por ejemplo, las +imágenes prefabricadas con paquetes de la sección non-free se crean +simplemente añadiendo #{--archive-areas "main contrib non-free"}#. + +Si se desea, se puede definir un método abreviado en la configuración de +Git, añadiendo lo siguiente al fichero #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +Esto permite utilizar #{lso:}# en cualquier lugar en que se tenga que +especificar la dirección de un repositorio git de #{live-systems.org}#. Si +se omite el sufijo #{.git}#, comenzar una nueva imagen con esta +configuración es tan fácil como: + +code{ + + $ lb config --config lso:live-images + +}code + +Clonar el repositorio #{live-images}# completo copiará todas las +configuraciones utilizadas para varias imágenes. Si se quiere construir una +imagen diferente después de haber terminado con la primera, cambiar a otro +directorio y de nuevo, y opcionalmente, hacer los cambios necesarios para +adaptarlo según las necesidades. + +En cualquier caso, recordar que cada vez que se tiene que construir una +imagen hay que hacerlo como superusuario: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/es/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/es/user_overview.ssi new file mode 100644 index 0000000..7882e22 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/es/user_overview.ssi @@ -0,0 +1,144 @@ +:B~ Descripción general de las herramientas + +1~overview-of-tools Descripción general de las herramientas + +Este capítulo contiene una descripción general de las tres herramientas +principales utilizadas en la creación de sistemas en vivo: live-build, +live-boot y live-config. + +2~live-build El paquete live-build + +live-build es una colección de scripts para generar los sistemas en vivo. A +estos scripts también se les conoce como «comandos». + +La idea detrás de live-build es ser un marco que utiliza un directorio de +configuración para automatizar completamente y personalizar todos los +aspectos de la creación de una imagen de un sistema en vivo. + +Muchos conceptos son similares a los utilizados para crear paquetes Debian +con /{debhelper}/: + +_* Los scripts tienen una ubicación central para la configuración de su +funcionamiento. En /{debhelper}/, éste es el subdirectorio #{debian/}# de un +árbol de paquetes. Por ejemplo, dh_install buscará, entre otros, un fichero +llamado #{debian/install}# para determinar qué ficheros deben existir en un +paquete binario en particular. De la misma manera, live-build almacena toda +su configuración bajo un subdirectorio #{config/}#. + +_* Los scripts son independientes - es decir, siempre es seguro ejecutar +cada comando. + +A diferencia de /{debhelper}/, live-build contiene las herramientas para +crear un directorio de configuración en esqueleto. Esto podría ser +considerado como similar a herramientas tales como /{dh-make}/. Para obtener +más información acerca de estas herramientas, seguir leyendo, ya que el +resto de esta sección trata sobre los cuatro comandos más importantes. En +interesante notar que están precedidos por #{lb}# que es una función +genérica para todos los comandos de live-build. + +_* *{lb config}*: Responsable de inicializar un directorio de configuración +para la creación de un sistema en vivo. Ver {El comando lb config}#lb-config +para más información. + +_* *{lb build}*: Responsable de iniciar la creación de un sistema en +vivo. Ver {El comando lb build}#lb-build para más información. + +_* *{lb clean}*: Responsable de la eliminación de partes de la creación de +un sistema en vivo. Ver {El comando lb clean}#lb-clean para más +información. + +3~lb-config El comando #{lb config}# + +Como se comentó en {live-build}#live-build, los scripts que componen +live-build obtienen su configuración gracias al comando #{source}# desde un +único directorio llamado #{config/}#. Como la creación de este directorio a +mano sería largo y propenso a errores, se puede utilizar el comando #{lb +config}# para crear el esqueleto de directorios de configuración inicial. + +Ejecutar #{lb config}# sin argumentos crea el subdirectorio #{config/}# que +se completa con algunas opciones por defecto en ficheros de configuración y +dos árboles de subdirectorios en forma de esqueleto llamados #{auto/}# y +#{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Utilizar #{lb config}# sin ningún argumento sería conveniente para los +usuarios que necesitan una imagen muy básica, o que tienen intención de +proporcionar, más adelante, una configuración más completa a través de +#{auto/config}# (ver {Gestionar una configuración}#managing-a-configuration +para más detalles). + +Normalmente, se tendrá que especificar algunas opciones. Por ejemplo, para +especificar que gestor de paquetes se desea utilizar durante la construcción +de la imagen: + +code{ + + $ lb config --apt aptitude + +}code + +Es posible especificar muchas opciones, tales como: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +Una lista completa de opciones está disponible en la página de manual +#{lb_config}#. + +3~lb-build El comando #{lb build}# + +El comando #{lb build}# lee la configuración del directorio #{config/}#. A +continuación, ejecuta los comandos de nivel inferior necesarios para crear +el sistema en vivo. + +3~lb-clean El comando #{lb clean}# + +El comando #{lb clean}# es el encargado de eliminar varias partes de una +creación de forma que las creaciones posteriores puedan comenzar de forma +limpia. Por defecto se eliminan las etapas #{chroot}#, #{binary}# y +#{source}# pero se deja el caché intacto. Además, se pueden limpiar etapas +de forma individual. Por ejemplo, si se han realizado cambios que sólo +afectan a la etapa binary, se debe usar #{lb clean --binary}# antes de crear +una nueva binary. Si los cambios modifican el bootstrap y/o los cachés de +paquetes, por ejemplo, cambios en las opciones #{--mode}#, +#{--architecture}# o #{--bootstrap}#, se debe utilizar #{lb clean +--purge}#. Ver el manual de #{lb_clean}# para una lista detallada de todas +sus opciones. + +2~live-boot El paquete live-boot + +live-boot es una colección de scripts que proporcionan ganchos (hooks) para +/{initramfs-tools}/, que sirve para generar un initramfs capaz de arrancar +sistemas en vivo, tales como los creados por live-build. Esto incluye +imágenes ISO, archivos comprimidos en formato tar para el arranque en red, e +imágenes para llaves USB. + +En el momento del arranque, buscará en los medios de almacenamiento de sólo +lectura un directorio #{/live/}# donde se encuentra un sistema de ficheros +raíz (a menudo una imagen del sistema de ficheros comprimidos como +squashfs). Si lo encuentra, creará un entorno de escritura, utilizando aufs, +para que arranquen los sistemas tipo Debian. + +Se puede encontrar más información sobre ramfs inicial en Debian en el +Manual del kernel Debian Linux en http://kernel-handbook.alioth.debian.org/ +concretamente en el capítulo sobre initramfs. + +2~live-config El paquete live-config + +live-config consiste en una serie de scripts que se ejecutan en el arranque +después de live-boot para configurar el sistema en vivo de forma +automática. Se ocupa de tareas como la creación del nombre del equipo +(hostname), las variantes locales y la zona horaria, crear el usuario en +vivo, la inhibición de trabajos de cron y el inicio de sesión automático del +usuario en vivo. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/about_manual.ssi new file mode 100644 index 0000000..30335d6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/about_manual.ssi @@ -0,0 +1,290 @@ +:B~ À propos de ce manuel + +1~about-manual À propos de ce manuel + +L'objectif principal de ce manuel est de servir de point d'accès unique à +tous les documents liés au ${project} et particulièrement aux logiciels +produits par le projet pour Debian 9.0 «${stable}». Une version mise à jour +peut toujours être trouvée sur http://live-systems.org/ . + +Ce manuel a principalement pour but de vous aider à construire un système +live et non pas de s'articuler autour des sujets relatifs à l'utilisateur +final. Toutefois, l'utilisateur final peut trouver des informations utiles +dans ces sections: {Les Bases}#the-basics couvrent le téléchargement des +images précompilées et la préparation des images pour être démarrées sur les +supports ou sur le réseau, soit en utilisant le constructeur web, soit en +exécutant live-build directement sur le système. {Personnalisation des +comportements pendant l'exécution}#customizing-run-time-behaviours décrit +certaines options qui peuvent être indiquées à l'invite de démarrage, telles +que la sélection d'un clavier, des paramètres régionaux et la persistance. + +Certaines commandes mentionnées dans le texte doivent être exécutées avec +les privilèges de super-utilisateur, qui peuvent être obtenus à l'aide de la +commande #{su}# ou en utilisant #{sudo}#. Afin de distinguer les commandes +qui peuvent être exécutées par un utilisateur sans privilège de celles +nécessitant les privilèges de super-utilisateur, les commandes sont +précédées respectivement par #{$}# ou #{#}#. Notez que ce symbole ne fait +pas partie de la commande. + +2~ Pour les impatients + +Même si nous croyons que tout dans ce manuel est important pour au moins +certains de nos utilisateurs, nous nous rendons compte qu'il y a beaucoup de +matière à couvrir et que vous pouvez vouloir expérimenter avant d'entrer +dans les détails. Par conséquent, nous vous suggérons de lire dans l'ordre +suivant. + +Tout d'abord, lisez ce chapitre {À propos de ce manuel}#about-manual dès le +début et finissant avec la section {Terminologie}#terms. Ensuite, passez aux +trois tutoriels à l'avant de la section {Exemples}#examples destinée à vous +apprendre la construction de l'image et les bases de la +personnalisation. Lisez en premier {En utilisant les +exemples}#using-the-examples, puis {Tutoriel 1: Une image par +défaut}#tutorial-1, {Tutoriel 2: Un logiciel de navigateur Web}#tutorial-2 +et finalement {Tutoriel 3: Une image personnalisée}#tutorial-3. À la fin de +ces tutoriels, vous aurez un avant-goût de ce qui peut être fait avec les +systèmes live. + +Nous vous encourageons à revenir à l'étude plus approfondie du manuel, en +poursuivant par exemple votre lecture par {Les bases}#the-basics, +{Construire une image netboot}#building-netboot-image et finissant par la +lecture de la {Vue d'ensemble de la personnalisation}#customization-overview +et les sections suivantes. Après cela, nous espérons que vous serez +complètement excités par ce qui peut être fait avec les systèmes live et +motivés pour lire le reste du manuel, du début à la fin. + +2~terms Terminologie + +_* *{Système Live}*: Un système d'exploitation pouvant être démarré sans +installation préalable sur un disque dur. Les systèmes live ne modifient pas +le système d'exploitation local ou les fichiers installés sur le disque dur +sans qu'on leur en donne explicitement l'instruction. D'habitude, les +systèmes live sont démarrés à partir des supports tels que des CDs, DVDs, ou +des clés USB. Certains systèmes peuvent également être démarrés sur le +réseau (via des images netboot, voir {Construction d'une image +netboot}#building-netboot-image), et sur l'Internet (via le paramètre +d'amorçage #{fetch=URL}#, voir {Webbooting}#webbooting). + +_* *{Support live}*: À la différence du système live, le support live se +réfère au CD, DVD ou clé USB où l'image binaire produite par live-build et +utilisée pour démarrer le système live est écrite. D'une manière générale, +le terme désigne également tout emplacement où réside l'exécutable qui +permet de démarrer le système live, tel que l'emplacement des fichiers de +démarrage sur le réseau. + +_* *{${project}}*: Le projet qui maintient, entre autres, les paquets +live-boot, live-build, live-config live-tools et live-manual. + +_* *{Système hôte}*: L'environnement utilisé pour créer le système live. + +_* *{Système cible}*: L'environnement utilisé pour faire fonctionner le +système live. + +_* *{live-boot}*: Une collection de scripts utilisés pour lancer des +systèmes live. + +_* *{live-build}*: Une collection de scripts utilisés pour construire des +systèmes live personnalisés. + +_* *{live-config}*: Une collection de scripts utilisés pour configurer un +système live pendant le processus d'amorçage. + +_* *{live-tools}*: Une collection de scripts supplémentaires utilisés pour +effectuer des tâches utiles dans un système live en fonctionnement. + +_* *{live-manual}*: Ce document est maintenu dans un paquet nommé +live-manual. + +_* *{Debian Installer (d-i)}*: Le système d'installation officiel pour la +distribution Debian. + +_* *{Paramètres d'amorçage}*: Les paramètres qui peuvent être entrés à +l'invite de démarrage afin de modifier le noyau ou live-config. + +_* *{chroot}*: Le logiciel /{chroot}/, #{chroot(8)}#, nous permet d'exécuter +plusieurs instances concurrentes de l'environnement GNU/Linux sur un système +sans redémarrage. + +_* *{Image binaire}*: Un fichier contenant le système live, tel que +live-image-i386.hybrid.iso ou live-image-i386.img. + +_* *{Distribution cible}*: La distribution sur laquelle votre système live +sera basée. Celle-ci peut être différente de la distribution de votre +système hôte. + +_* *{stable/testing/unstable}*: La distribution *{stable}*, actuellement +nommée ${stable}, contient la dernière version officielle de Debian. La +distribution *{testing}*, temporairement nommée ${testing}, est la prochaine +version *{stable}* où seulement les paquets suffisamment matures peuvent +entrer. Un avantage de cette distribution est qu'elle contient des logiciels +de versions plus récentes que la version *{stable}*. La distribution +*{unstable}*, nommée sid de façon permanente, est en constante évolution. En +général cette distribution est utilisée par les développeurs et ceux qui +aiment le risque. Tout au long du manuel, nous avons tendance à utiliser les +noms de code pour les évolutions majeures, tels que ${testing} ou sid, car +c'est ce qui est pris en charge par les outils eux-mêmes. + +2~ Auteurs + +La liste des auteurs (dans l'ordre alphabétique): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contribuer à ce document + +Ce manuel est conçu comme un projet communautaire et toutes les propositions +d'améliorations et de contributions sont bienvenues. Veuillez consulter la +section {Contribuer au projet}#contributing-to-project pour des informations +détaillées sur la façon d'obtenir une clé et de faire des livraisons +(commits). + +3~applying-changes Appliquer des modifications + +Afin d'apporter des modifications au manuel anglais, vous devez modifier les +fichiers adéquats dans #{manual/en/}# mais avant de soumettre votre +contribution, veuillez prévisualiser votre travail. Afin de prévisualiser +live-manual, assurez-vous que les paquets nécessaires sont installés en +exécutant: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Vous pouvez compiler live-manual dans le répertoire de niveau supérieur de +votre Git checkout en exécutant: + +code{ + + $ make build + +}code + +Comme il faut un certain temps pour construire le manual dans toutes les +langues prises en charge, les auteurs peuvent trouver pratique d'utiliser +l'un des raccourcis de construction rapide lors de la révision de la +nouvelle documentation ajoutée au manuel anglais. #{PROOF=1}# construit +live-manual au format html, mais sans les fichiers html segmentés, et +#{PROOF=2}# construit live-manual au format pdf, mais seulement les +portraits A4 et US. C'est pourquoi l'utilisation de l'une ou l'autre des +possibilités peut sauver une quantité considérable de temps, par exemple: + +code{ + + $ make build PROOF=1 + +}code + +Lors de la révision d'une des traductions, il est possible de construire une +seule langue en exécutant, par exemple: + +code{ + + $ make build LANGUAGES=de + +}code + +Il est également possible de construire par type de document, par exemple, + +code{ + + $ make build FORMATS=pdf + +}code + +Ou combiner les deux, par exemple: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +Après avoir relu votre travail et vous être assuré que tout va bien, +n'utilisez pas #{make commit}# à moins que vous mettiez à jour les +traductions dans le commit. Dans ce cas, ne mélangez pas les modifications +apportées au manuel en anglais et les traductions dans la même livraison, +mais utilisez des commits séparés. Consultez la section +{Traduction}#translation pour plus de détails. + +3~translation Traduction + +Afin de traduire live-manual, procédez comme suit, selon que vous commencez +une traduction à partir de zéro ou vous travaillez sur une traduction déjà +existante: + +_* Commencer une nouvelle traduction à partir de zéro + +_2* Traduisez les fichiers *{about_manual.ssi.pot}*, +*{about_project.ssi.pot}* et *{index.html.in.pot}* dans #{manual/pot/}# dans +votre langue avec votre éditeur préféré (comme /{poedit}/). Envoyez les +fichiers #{.po}# traduits à la liste de diffusion pour vérifier leur +intégrité. La vérification d'intégrité de live-manual garantit non seulement +que les fichiers #{.po}# sont 100% traduits, mais elle détecte également des +erreurs possibles. + +_2* Pour activer une nouvelle langue dans l'autobuild, il suffit d'ajouter +les premiers fichiers traduits à #{manual/po/${LANGUAGE}/}# et lancer #{make +commit}#. Modifier ensuite #{manual/_sisu/home/index.html}# en ajoutant le +nom de la langue et son nom en anglais entre parenthèses. + +_* Continuer avec une traduction déjà commencée + +_2* Si votre langue cible a déjà été ajoutée, vous pouvez continuer avec la +traduction des fichiers .po dans #{manual/po/${LANGUAGE}/}# de façon +aléatoire avec votre éditeur préféré (comme /{poedit}/). + +_2* N'oubliez pas que vous devez faire un #{make commit}# pour assurer que +la traduction des manuels est mise à jour à partir des fichiers .po, alors +vous pouvez réviser vos modifications avec #{make build}# avant #{git add +.}#, #{git commit -m "Translating..."}# et #{git push}#. Gardez à l'esprit +que #{make build}# peut prendre un temps considérable, vous pouvez relire +les langues individuellement comme expliqué dans {Appliquer des +modifications}#applying-changes + +Après l'exécution de #{make commit}#, vous verrez beaucoup de texte sur +l'écran. Il s'agit essentiellement de messages informatifs sur l'état du +processus et de quelques indications sur ce qui peut être fait pour +améliorer live-manual. Si vous ne voyez aucune erreur fatale, vous pouvez +généralement continuer et soumettre votre contribution. + +live-manual contient deux utilitaires qui peuvent grandement aider les +traducteurs à trouver les textes non traduits et modifiés. Le premier est +"make translate". Il lance un script qui vous indique en détail le nombre de +messages non traduits qu'il y a dans chaque fichier .po. Le second, "make +fixfuzzy", n'agit que sur les messages modifiés, mais il vous aide à les +trouver et à les résoudre un par un. + +Gardez à l'esprit que même si ces utilitaires peuvent être vraiment utiles +pour faire un travail de traduction sur la ligne de commande, l'utilisation +d'un outil spécialisé comme /{poedit}/ est la méthode recommandée pour +effectuer la tâche. C'est aussi une bonne idée de lire la documentation sur +localisation de debian (l10n) et, plus particulièrement pour live-manual, +les {Lignes directrices pour les traducteurs}#guidelines-translators. + +*{Remarque:}* Vous pouvez utiliser #{make clean}# pour nettoyer votre arbre git avant de faire un push. Cette étape n'est pas obligatoire grâce au fichier .gitignore mais c'est une bonne pratique pour éviter d'envoyer certains fichiers involontairement. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/about_project.ssi new file mode 100644 index 0000000..bb2f16c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/about_project.ssi @@ -0,0 +1,111 @@ +:B~ À propos du ${project} + +1~about-project À propos du ${project} + +2~ Motivation + +3~ Ce qui ne va pas avec les systèmes live actuels + +Lorsque le ${project} a été lancé, il y avait déjà plusieurs systèmes live +basés sur Debian et ils faisaient un excellent travail. Du point de vue de +Debian, la plupart d'entre eux ont un ou plusieurs des inconvénients +suivants: + +_* Ce ne sont pas des projets Debian et ils manquent donc de soutien au sein +de Debian. + +_* Ils mélangent des distributions différentes comme *{testing}* et +*{unstable}*. + +_* Ils ne prennent en charge que i386. + +_* Ils modifient le comportement et/ou l'apparence des paquets en les +dépouillant pour économiser de l'espace. + +_* Ils comprennent des paquets ne provenant pas de l'archive Debian. + +_* Ils offrent des noyaux personnalisés avec des correctifs supplémentaires +qui ne font pas partie de Debian. + +_* Ils sont gros et lents en raison de leur dimension et donc pas +recommandés comme systèmes de sauvetage. + +_* Ils ne sont pas disponibles en différents formats (CDs, DVDs, clés USB et +images netboot). + +3~ Pourquoi créer notre propre système live? + +Debian est le système d'exploitation universel: Debian a un système live +pour servir de vitrine et pour représenter le vrai, seul et unique système +Debian avec les principaux avantages suivants: + +_* C'est un sous-projet de Debian. + +_* Il reflète l'état (actuel) d'une distribution. + +_* Il fonctionne sur le plus grand nombre d'architectures possible. + +_* Il ne se compose que de paquets Debian inchangés. + +_* Il ne contient pas de paquets qui n'appartenant pas à l'archive Debian. + +_* Il utilise un noyau Debian inchangé, sans correctifs supplémentaires. + +2~ Philosophie + +3~ Seulement des paquets inchangés de Debian «main» + +Nous n'utiliserons que les paquets du dépôt Debian dans la section +«main». La section non-free ne fait pas partie de Debian et ne peut donc pas +être utilisée pour les images officielles du système live. + +Nous ne changerons pas les paquets. Chaque fois que nous aurons besoin de +changer quelque chose, nous le ferons en coordination avec le responsable du +paquet dans Debian. + +À titre d'exception, nos propres paquets tels que live-boot, live-build ou +live-config peuvent être utilisés temporairement à partir de notre propre +dépôt pour des raisons de développement (par exemple pour créer des +instantanés de développement). Ils seront téléchargés sur Debian +régulièrement. + +3~ Pas de configuration des paquets du système live + +Dans cette phase, nous n'offrirons pas de configurations alternatives. Tous +les paquets sont utilisés dans leur configuration par défaut comme ils sont +après une installation standard de Debian. + +Chaque fois que nous aurons besoin d'une configuration par défaut +différente, nous la ferons en coordination avec le responsable du paquet +dans Debian. + +Un système de configuration des paquets est fourni avec debconf permettant +la personnalisation des paquets installés sur vos images live, mais pour les +{images live précompilées}#downloading-prebuilt-images seulement une +configuration par défaut sera utilisée sauf si c'est absolument nécessaire +pour fonctionner dans l'environnement live. Autant que possible, nous +préférons adapter les paquets dans l'archive Debian de sorte qu'ils +fonctionnent mieux dans un système live plutôt que faire des changements à +l'ensemble d'outils live ou les {configurations des images +live}#clone-configuration-via-git. Pour plus d'informations, veuillez +consulter {Vue d'ensemble de la personnalisation}#customization-overview. + +2~contact Contact + +_* *{Liste de diffusion}*: Le contact principal du projet est la liste de +diffusion https://lists.debian.org/debian-live/. Vous pouvez envoyer un +courriel à la liste directement en adressant votre courrier à +debian-live@lists.debian.org. Les archives de la liste sont disponibles sur +https://lists.debian.org/debian-live/. + +_* *{IRC}*: Un certain nombre d'utilisateurs et de développeurs sont +présents dans le canal #debian-live sur irc.debian.org (OFTC). Quand vous +posez une question sur IRC, s'il vous plaît soyez patient en attendant une +réponse. Si aucune réponse n'est donnée, veuillez envoyer un courriel à la +liste de diffusion. + +_* *{BTS}*: Le {Système de suivi des bogues}https://www.debian.org/Bugs/ +(BTS) contient les détails des bogues signalés par les utilisateurs et les +développeurs. Chaque bogue reçoit un numéro et est conservé jusqu'à ce qu'il +soit marqué comme traité. Pour plus d'informations, veuillez consulter +{Rapporter des bogues}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/appendix_style-guide.ssi new file mode 100644 index 0000000..7217a77 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/appendix_style-guide.ssi @@ -0,0 +1,390 @@ +:B~ Guide de style + +1~style-guide Guide de style + +2~ Lignes directrices pour les auteurs + +Cette section traite des considérations générales à prendre en compte lors +de la rédaction de la documentation technique pour live-manual. Elles sont +divisées en caractéristiques linguistiques et en procédures recommandées. + +*{Remarque:}* Les auteurs doivent lire d'abord {Contribuer à ce document}#how-to-contribute + +3~ Caractéristiques linguistiques + +_* /{Utilisez un anglais simple}/ + +Gardez à l'esprit qu'un pourcentage élevé de vos lecteurs ne sont pas de +langue maternelle anglaise. Donc, en règle générale, essayez d'utiliser des +phrases significatives courtes, suivies d'un point. + +Cela ne signifie pas que vous devez utiliser un style naïf et simpliste. Il +s'agit d'une suggestion pour essayer d'éviter, autant que possible, phrases +subordonnées complexes qui rendent le texte difficile à comprendre pour les +locuteurs non natifs de l'anglais. + +_* /{Variété de l'anglais}/ + +Les variétés les plus répandues de l'anglais sont la britannique et +l'américain, donc il est très probable que la plupart des auteurs utilisent +l'un ou l'autre. Dans un environnement collaboratif, la variété idéale +serait «l'anglais international», mais il est très difficile, pour ne pas +dire impossible, de se prononcer sur quelle variété parmi toutes celles qui +existent déjà, est la meilleure à utiliser. + +Nous croyons que les différentes variétés peuvent se mélanger sans créer +incompréhensions, mais en termes généraux, vous devriez essayer d'être +cohérent et avant de décider entre britannique, américain ou toute autre +variété anglaise à votre discrétion, s'il vous plaît jeter un oeil à la +façon dont d'autres gens écrivent et essayer de les imiter. + +_* /{Soyez équilibré}/ + +Ne soyez pas partial. Évitez d'inclure des références à des idéologies +totalement étrangères à live-manual. L'écriture technique doit être aussi +neutre que possible. Il est dans la nature même de l'écriture scientifique. + +_* /{Soyez politiquement correct}/ + +Essayez d'éviter un langage sexiste autant que possible. Si vous avez besoin +de faire référence à la troisième personne du singulier, de préférence +utilisez «they» plutôt que «he» ou «she» ou inventions maladroites telles +que «s/he», «s(he)», etc. + +_* /{Soyez concis}/ + +Allez droit au but et ne pas errer sans but. Donner autant d'informations +que nécessaire, mais ne donnez pas plus d'informations que nécessaire, +c'est-à-dire, ne pas expliquer les détails inutiles. Vos lecteurs sont +intelligents. Présumez une certaine connaissance préalable de leur part. + +_* /{Minimiser le travail de traduction}/ + +Gardez à l'esprit que ce que vous écrivez devra être traduit dans plusieurs +autres langues. Cela implique qu'un certain nombre de gens devront faire un +travail supplémentaire si vous ajoutez des informations inutiles ou +redondantes. + +_* /{Soyez cohérent}/ + +Comme suggéré précédemment, il est presque impossible de normaliser un +document collaboratif dans un ensemble parfaitement unifié. Cependant, tous +les efforts de votre côté pour écrire d'une manière cohérente avec le reste +des auteurs seront appréciés. + +_* /{Soyez cohésive}/ + +Utilisez autant de dispositifs de formation de texte que nécessaire pour +rendre votre texte cohésive et sans ambiguïtés. (Les dispositifs de +formation de texte sont des marqueurs linguistiques tels que les +connecteurs). + +_* /{Soyez descriptif}/ + +Il est préférable de décrire le point en une ou plusieurs paragraphes que +simplement en utilisant un certain nombre de phrases dans un style typique +"changelog". Décrivez-le! Vos lecteurs apprécieront ça. + +_* /{Dictionnaire}/ + +Cherchez le sens des mots dans un dictionnaire ou une encyclopédie si vous +ne savez pas comment exprimer certaines notions en anglais. Mais gardez à +l'esprit qu'un dictionnaire peut être votre meilleur ami ou peut se +transformer en votre pire ennemi si vous ne savez pas comment l'utiliser +correctement. + +L'anglais possède le plus grand vocabulaire qui existe (avec plus d'un +million de mots). Beaucoup de ces mots sont des emprunts d'autres +langues. Lorsque l'on regarde le sens des mots dans un dictionnaire +bilingue, la tendance d'un locuteur non natif de l'anglais est de choisir +celui qui sonne plus similaire dans leur langue maternelle. Cela se +transforme souvent en un discours excessivement formelle qui ne semble pas +tout à fait naturel en anglais. + +En règle générale, si un concept peut être exprimé en utilisant différents +synonymes, c'est un bon conseil choisir le premier mot proposé par le +dictionnaire. En cas de doute, le choix des mots d'origine germanique +(Habituellement mots monosyllabiques) est souvent la bonne chose à faire. Il +faut savoir que ces deux techniques peuvent produire un discours plutôt +informel, mais au moins votre choix des mots sera d'utilisation grand et +généralement accepté. + +L'utilisation d'un dictionnaire de collocations est recommandé. Ils sont +extrêmement utiles quand il s'agit de savoir quels mots surviennent +généralement ensemble. + +Encore une fois, c'est une bonne pratique apprendre à partir du travail des +autres. Grâce à un moteur de recherche pour vérifier comment les autres +auteurs utilisent certaines expressions peut aider beaucoup. + +_* /{Faux amis, expressions idiomatiques et autres expressions}/ + +Attention aux faux amis. Peu importe comment vous êtes compétent dans une +langue étrangère, vous ne pouvez pas vous empêcher de tomber de temps en +temps dans le piège de ce qu'on appelle les «faux amis», des mots qui se +ressemblent dans les deux langues, mais dont les significations ou les +utilisations pourrait être complètement différent. + +Essayez d'éviter les expressions idiomatiques autant que possible. Les +expressions idiomatiques sont des expressions qui peuvent transmettre un +sens complètement différent de ce que leurs mots individuels semblent +signifier. Parfois, les expressions idiomatiques peuvent être difficiles à +comprendre, même pour les locuteurs natifs de l'anglais! + +_* /{Évitez l'argot, les abréviations, les contractions...}/ + +Même si vous êtes encouragés à utiliser un langage simple, l'anglais de tous +les jours, la rédaction technique appartient au registre formel de la +langue. + +Essayez d'éviter l'argot, abréviations inhabituels qui sont difficiles à +comprendre et surtout les contractions qui tentent d'imiter le langage +parlé. Sans oublier typique expressions d'irc et favorables à la famille. + +3~ Procédures + +_* /{Tester avant d'écrire}/ + +Il est important que les auteurs testent leurs exemples avant de les ajouter +à live-manual pour s'assurer que tout fonctionne comme décrit. Tester sur +un chroot propre ou une machine virtuelle peut être un bon point de +départ. Par ailleurs, il serait idéal si les tests ont ensuite été effectués +sur des machines différentes avec un matériel différent pour repérer +d'éventuels problèmes qui pourraient survenir. + +_* /{Exemples}/ + +En fournissant un exemple essayer d'être aussi précis que possible. Un +exemple est, après tout, juste un exemple. + +Il est souvent préférable d'utiliser une ligne qui ne s'applique qu'à un cas +particulier que l'utilisation d'abstractions qui peuvent confondre vos +lecteurs. Dans ce cas, vous pouvez fournir une brève explication des effets +de l'exemple proposé. + +Il peut y avoir des exceptions lorsque l'exemple suggère d'utiliser +certaines commandes potentiellement dangereuses qui, si elles sont mal +utilisées, peuvent causer des pertes de données ou d'autres effets +indésirables similaires. Dans ce cas, vous devez fournir une explication +approfondie des effets secondaires possibles. + +_* /{Liens externes}/ + +Les liens externes ne doivent être utilisés lorsque l'information sur ces +sites est cruciale quand il s'agit de comprendre un point particulier. Même +si, essayez d'utiliser des liens externes aussi peu que possible. Les liens +internet sont susceptibles de changer de temps en temps résultant en des +liens brisés et en laissant vos arguments dans un état incomplet. + +D'ailleurs, les gens qui lisent le manuel hors ligne n'auront pas la chance +de suivre ces liens. + +_* /{Évitez les marques et les choses qui violent la licence sous laquelle +le manuel est publié}/ + +Essayez d'éviter les marques autant que possible. Gardez à l'esprit que +d'autres projets peuvent utiliser la documentation que vous écrivez. Donc, +vous compliquez les choses pour eux si vous ajoutez certaines matières +spécifiques. + +live-manual est sous la licence GNU GPL. Cela a un certain nombre de +conséquences qui s'appliquent à la distribution de la matière (de toute +nature, y compris les graphiques ou logos protégées) qui est publiée avec le +manuel. + +_* /{Ecrire un premier projet, réviser, modifier, améliorer, refaire si +nécessaire}/ + + - Remue-méninges!. Vous devez organiser vos idées d'abord dans une séquence + logique des événements. + + - Une fois que vous avez en quelque sorte organisé ces idées dans votre + esprit écrire un premier projet. + + - Réviser la grammaire, la syntaxe et l'orthographe. Gardez à l'esprit que + les noms propres des versions, tels que ${testing} ou sid, ne doivent pas + être capitalisés lorsqu'ils sont utilisés comme noms de code. Pour + vérifier l'orthographe, on peut exécuter la cible "spell". C'est à dire, + #{make spell}# + + - Améliorer vos phrases et refaire n'importe quelle partie si nécessaire. + +_* /{Chapitres}/ + +Utilisez le système de numérotation classique des chapitres et +sous-titres. Par exemple 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, +2.1 ... et cetera. Voir marqueurs ci-dessous. + +Si vous avez d'énumérer une série d'étapes ou phases dans votre description, +vous pouvez également utiliser des nombres ordinaux: premier, deuxième, +troisième ... ou d'abord, puis, après cela, enfin ... Sinon, vous pouvez +utiliser les éléments à puces. + +_* /{Balisage}/ + +Et finalement, live-manual utilise {SiSU}http://www.sisudoc.org/ pour +traiter les fichiers texte et pour produire plusieurs formats. Il est +recommandé de consulter le {manuel +SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html pour se +familiariser avec son balisage, ou bien tapez: + +code{ + + $ sisu --help markup + +}code + +Voici quelques exemples de balisage qui peuvent éventuellement vous aider: + + - Pour accent/texte en gras: + +code{ + +*{foo}* or !{foo}! + +}code + +il produit: *{foo}* or !{foo}!. Utiliser pour mettre l'accent sur certains +mots-clés. + + - Pour italique: + +code{ + +/{foo}/ + +}code + +il produit: /{foo}/. Utiliser par exemple, pour les noms des paquets Debian. + + - Pour monospace: + +code{ + +#{foo}# + +}code + +il produit: #{foo}#. Utiliser par exemple, pour les noms des commandes. Et +aussi pour souligner certains mots clés ou des choses comme les chemins. + + - Pour les blocs de code: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +il produit: + +code{ + + $ foo + # bar + +}code + +Utilisez #{code{}# pour ouvrir et #{}code}# pour fermer les balises. Il est +important de se rappeler de laisser un espace au début de chaque ligne de +code. + +2~guidelines-translators Lignes directrices pour les traducteurs + +Cette section traite des considérations générales à prendre en compte lors +de la traduction du contenu du live-manual. + +Comme recommandation générale, les traducteurs doivent avoir lu et compris +les règles de traduction qui s'appliquent à leurs langues +spécifiques. Habituellement, les groupes de traduction et listes de +diffusion fournissent des informations sur la façon de produire un travail +de traduction qui respecte les normes de qualité de Debian. + +*{Remarque:}* Les traducteurs doivent aussi lire {Contribuer à ce document}#how-to-contribute. En particulier, la section {Traduction}#translation + +3~ Conseils de traduction + +_* /{Commentaires}/ + +Le rôle du traducteur est de transmettre le plus fidèlement possible le sens +des mots, des phrases, des paragraphes et des textes comme écrit par les +auteurs originaux dans leur langue cible. + +Donc, ils devraient s'abstenir d'ajouter des commentaires personnels ou des +morceaux d'informations supplémentaires de leur propre chef. S'ils veulent +ajouter un commentaire pour d'autres traducteurs travaillant sur les mêmes +documents, ils peuvent le laisser dans l'espace réservé pour cela. Autrement +dit, l'en-tête des chaînes dans les fichiers *{po}* précédés d'un signe +*{#}*. Nombreuses logiciels de traduction graphiques peuvent gérer +automatiquement ces types de commentaires. + +_* /{NDT, Note Du Traducteur}/ + +Il est parfaitement acceptable cependant, inclure un mot ou une expression +entre parenthèses dans le texte traduit si, et seulement si, cela fait le +sens d'un mot ou d'une expression difficile plus clair pour le lecteur. A +l'intérieur des parenthèses, le traducteur doit mettre en évidence que +l'addition a été leur en utilisant l'abréviation "NDT" ou "Note Du +Traducteur ". + +_* /{Phrases impersonnelles}/ + +Les documents écrits en anglais font une utilisation intensive de la forme +impersonnelle "you". Dans d'autres langues qui ne partagent pas cette +caractéristique, ce pourrait donner la fausse impression que les textes +originaux traitent directement le lecteur quand en réalité ils ne le font +pas. Les traducteurs doivent être conscients de ce fait et traduir dans leur +langue le plus fidèlement que possible. + +_* /{Faux amis}/ + +Le piège des "faux amis" expliqué avant s'applique surtout aux +traducteurs. Vérifiez le sens des faux amis suspectes en cas de doute. + +_* /{Balisage}/ + +Les traducteurs qui travaillent d'abord avec les fichiers *{pot}* et plus +tard avec les fichiers *{po}* trouveront de nombreuses caractéristiques de +balisage dans les chaînes. Ils peuvent traduire le texte de toute façon, +tant qu'il est traduisible, mais il est extrêmement important qu'ils +utilisent exactement le même balisage que la version originale anglaise. + +_* /{Blocs de code}/ + +Même si les blocs de code sont généralement intraduisibles, les inclure dans +la traduction est la seule façon d'obtenir une traduction complète 100%. Et +même si cela signifie plus de travail au début car ça peut exiger +l'intervention des traducteurs si le code change, il est le meilleur moyen, +à long terme, d'identifier ce qui a déjà été traduit et ce qui n'a pas, lors +de la vérification de l'intégrité des fichiers .po. + +_* /{Sauts de ligne}/ + +Les textes traduits doivent avoir les mêmes sauts de lignes exactes que les +textes originaux. Veillez appuyer sur "Entrée" ou tapez *{\n}* si elles +apparaissent dans les fichiers originaux. Ces nouvelles lignes apparaissent +souvent, par exemple, dans les blocs de code. + +Ne vous méprenez pas, cela ne signifie pas que le texte traduit doit avoir +la même longueur que la version anglaise. C'est presque impossible. + +_* /{Chaînes intraduisibles}/ + +Les traducteurs ne doivent jamais traduire: + + - Les noms de code des versions (qui doivent être écrits en minuscules) + + - Les noms des logiciels + + - Les commandes fournies à titre d'exemples + + - Métadonnées (souvent entre deux points *{:metadata:}*) + + - Liens + + - Les chemins diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/examples.ssi new file mode 100644 index 0000000..a959f50 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/examples.ssi @@ -0,0 +1,461 @@ +:B~ Exemples + +1~examples Exemples + +Ce chapitre présente des exemples de constructions pour des cas +d'utilisation spécifiques avec des systèmes live. Si vous débutez dans la +construction de vos propres images des systèmes live, nous vous recommandons +de regarder d'abord les trois tutoriels à la suite car chacun d'entre eux +enseigne de nouvelles techniques qui vous aideront à utiliser et à +comprendre les exemples restants. + +2~using-the-examples Utiliser les exemples + +Pour utiliser ces exemples, vous avez besoin d'un système pour les +construire qui doit répondre aux exigences énumérées dans +{Exigences}#requirements et sur lequel live-build est installé comme décrit +dans {Installation de live-build}#installing-live-build. + +Notez que, pour des raisons de concision, dans ces exemples, nous +n'indiquons pas de miroir local à utiliser pour la construction. Vous pouvez +accélérer considérablement les téléchargements si vous utilisez un miroir +local. Vous pouvez indiquer ces options lorsque vous utilisez #{lb config}#, +tel que décrit dans {Miroirs de distribution utilisés pendant la +construction}#distribution-mirrors-build-time, ou pour plus de commodité, +fixez par défaut votre système de construction dans +#{/etc/live/build.conf}#. Il suffit de créer ce fichier et de définir les +variables #{LB_MIRROR_*}# correspondantes à votre miroir préféré. Tous les +autres miroirs utilisés dans la construction seront choisis par défaut à +partir de ces valeurs. Par exemple: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-updates/" + +}code + +2~tutorial-1 Tutoriel 1: Une image par défaut + +*{Cas d'utilisation:}* Créer une image simple d'abord, en apprenant les bases de live-build. + +Dans ce tutoriel, nous construirons une image ISO hybride par défaut +contenant uniquement des paquets de base (pas de Xorg) et quelques paquets +de prise en charge live, en guise de premier exercice dans l'utilisation de +live-build. + +Vous ne pouvez pas faire plus simple que cela: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examinez le contenu du répertoire #{config/}# si vous le souhaitez. Vous +verrez stockés ici une arborescence de configuration, prête à être +personnalisée ou, dans ce cas, utilisée immédiatement pour construire une +image par défaut. + +Maintenant, en tant que superutilisateur, construisez l'image en +enregistrant un journal avec #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +En supposant que tout se passe bien, après un certain temps, le répertoire +courant contiendra #{live-image-i386.hybrid.iso}#. Cette image ISO hybride +peut être démarrée directement dans une machine virtuelle comme décrit dans +{Test d'une image ISO avec QEMU}#testing-iso-with-qemu et {Test d'une image +ISO avec VirtualBox}#testing-iso-with-virtualbox, ou bien copiée sur un +support optique ou un périphérique USB comme décrit dans {Graver une image +ISO sur un support physique}#burning-iso-image et {Copie d'un image ISO +hybride sur une clé USB}#copying-iso-hybrid-to-usb, respectivement. + +2~tutorial-2 Tutoriel 2: Un utilitaire d'un navigateur Web + +*{Cas d'utilisation:}* Créer l'image d'un utilitaire de navigation Web, en apprenant à appliquer des personnalisations. + +Dans ce tutoriel, nous allons créer une image utilisable comme un utilitaire +de navigation web, ce qui servira d'introduction à la personnalisation +d'images live. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Notre choix de LXDE pour cet exemple reflète notre volonté de fournir un +environnement de bureau minimal, puisque le but de l'image est l'utilisation +unique que nous avons à l'esprit, le navigateur web. On pourrait aller +encore plus loin et offrir une configuration par défaut pour le navigateur +web dans #{config/includes.chroot/etc/iceweasel/profile/}#, ou des paquets +de prise en charge supplémentaires pour visualiser différents types de +contenu web, mais nous laissons cela en exercice pour le lecteur. + +Construisez l'image, encore une fois en tant que superutilisateur, et gardez +un journal comme dans {Tutoriel 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Encore une fois, vérifiez que l'image est OK et faites un test, comme dans +{Tutoriel 1}#tutorial-1: + +2~tutorial-3 Tutoriel 3: Une image personnalisée + +*{Cas d'utilisation:}* Créer un projet pour construire une image personnalisée, contenant vos logiciels préférés à emporter avec vous sur une clé USB où que vous alliez, et évoluant dans des révisions successives selon les changements de vos besoins et de vos préférences. + +Puisque nous allons changer notre image personnalisée pendant un certain +nombre de révisions, et que nous voulons suivre ces changements, essayer des +choses expérimentalement et éventuellement les annuler si les choses ne +fonctionnent pas, nous garderons notre configuration dans le populaire +système de contrôle de version #{git}#. Nous allons également utiliser les +meilleures pratiques d'autoconfiguration via #{auto}# scripts tel que décrit +dans {Gestion d'une configuration}#managing-a-configuration. + +3~ Première révision + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Éditez #{auto/config}# comme suit: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Exécutez #{lb config}# pour générer l'arbre de configuration, en utilisant +le script #{auto/config}# qu'on a créé: + +code{ + + $ lb config + +}code + +Remplissez maintenant votre liste de paquets locaux: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +Tout d'abord, #{--architectures i386}# assure que sur notre système de +construction #{amd64}#, nous construisons une version de 32 bits qui peut +être utilisée sur la plupart des machines. Deuxièmement, nous utilisons +#{--linux-flavours 686-pae}# parce que nous ne prévoyons pas d'utiliser +cette image sur des systèmes très anciens. Troisièmement, nous avons choisi +le métapaque de la tâche /{lxde}/ pour nous donner un bureau minimal. Et +enfin, nous avons ajouté deux premiers paquets préférés: /{iceweasel}/ et +/{xchat}/. + +Maintenant, construisez l'image: + +code{ + + # lb build + +}code + +Notez que contrairement aux deux premiers tutoriels, nous n'avons plus +besoin de taper #{2>&1 | tee build.log}# parce que cela est maintenant +inclus dans #{auto/build}#. + +Une fois que vous avez testé l'image (comme dans {Tutoriel 1}#tutorial-1) et +vous êtes satisfait de son fonctionnement, il est temps d'initialiser notre +dépôt #{git}#, en n'ajoutant que les scripts auto que nous avons juste +créés, puis de faire le premier commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Deuxième révision + +Dans cette révision, nous allons nettoyer à partir de la première +construction, ajouter le paquet /{vlc}/ à notre configuration, reconstruire, +tester et faire le commit. + +La commande #{lb clean}# va nettoyer tous les fichiers générés par la +construction précédente à l'exception du cache, ce qui évite d'avoir à +retélécharger les paquets. Cela garantit que la commande #{lb build}# +suivante exécutera à nouveau toutes les étapes pour régénérer les fichiers +de notre nouvelle configuration. + +code{ + + # lb clean + +}code + +Ajoutez maintenant le paquet /{vlc}/ à votre liste de paquets locaux dans +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Construisez à nouveau: + +code{ + +# lb build + +}code + +Testez et, quand vous êtes satisfait, faites le commit de la prochaine +révision: + +code{ + + $ git commit -a -m "Ajout du lecteur de média vlc." + +}code + +Bien sûr, des changements plus compliqués de la configuration sont +possibles, comme l'ajout de fichiers dans les sous-répertoires de +#{config/}#. Quand vous livrez de nouvelles révisions, prenez soin de ne pas +modifier à la main ou d'envoyer dans le dépôt les fichiers de niveau +supérieur dans #{config}# contenant les variables #{LB_*}#, car ce sont +aussi des produits de lacreation et ils sont toujours nettoyés par #{lb +clean}# et recréés avec #{lb config}# via leurs scripts #{auto}# respectifs. + +Nous sommes arrivés à la fin de notre série de tutoriels. Alors que de +nombreux types de personnalisations sont possibles, même en n'utilisant que +les fonctionnalités explorées dans ces exemples simples, une variété presque +infinie d'images différentes peut être crée. Les autres exemples de cette +section couvrent plusieurs autres cas d'utilisation tirés des expériences +recueillies chez les utilisateurs des systèmes live. + +2~ Un client kioske VNC + +*{Cas d'utilisation:}* Créer une image avec live-build pour démarrer directement sur un serveur VNC. + +Créez un répertoire de construction et créez une configuration à +l'intérieur, désactivez «recommends» pour faire un système minimal. Puis +créez deux listes initiales de paquets: la première générée par un script +fourni par live-build nommée #{Packages}# (voir {Générer listes de +paquets}#generated-package-lists), et la seconde incluant /{xorg}/, +/{gdm3}/, /{metacity}/ et /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +Comme il est expliqué dans {Régler APT pour économiser de +l'espace}#tweaking-apt-to-save-space, il se peut que vous deviez ajouter +quelques paquets recommandés pour faire fonctionner votre image +correctement. + +Une façon facile d'énumérer les paquets recommendés est d'utiliser +/{apt-cache}/. Par exemple: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +Dans cet exemple, nous avons découvert que nous devions ré-inclure plusieurs +paquets recommandés par live-config et live-boot: #{user-setup}# pour +l'autologin et #{sudo}# un logiciel essentiel pour arrêter le système. En +outre, il pourrait être utile d'ajouter #{live-tools}# pour copier l'image +dans la RAM et #{eject}# pour éjecter le support live. Alors: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +Après cela, créez le répertoire #{/etc/skel}# dans +#{config/includes.chroot}# avec un fichier #{.xsession}# personnalisé pour +l'utilisateur par défaut qui va lancer /{metacity}/ et /{xvncviewer}/, en +reliant le port #{5901}# sur un serveur à #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Construire l'image: + +code{ + + # lb build + +}code + +Amusez-vous bien! + +2~ Une image de base pour une clé USB de 128 Mo + +*{Cas d'utilisation:}* Créer une image par défaut avec certains composants supprimés afin de l'adapter sur une clé USB de 128 Mo avec un peu d'espace laissé pour l'utiliser à votre convenance. + +Pour l'optimisation d'une image adaptée à la dimension de certains supports, +vous avez besoin de comprendre le compromis que vous faites entre la taille +et la fonctionnalité. Dans cet exemple, nous ne réduisons la taille que pour +faire place aux éléments supplémentaires dans la limite de 128 Mo, mais en +évitant de détruire l'intégrité des paquets contenus, telle que la purge des +données de localisation via le paquet /{localepurge}/, ou d'autres +optimisations "intrusives". On notera en particulier que nous utilisons +#{--debootstrap-options}# pour créer un système minimal à partir de zéro. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +Pour faire que l'image fonctionne correctement, nous devons ajouter à +nouveau au moins deux paquets recommandés qui sont laissés de côté par +l'option #{--apt-recommends false}#. Voir {Régler APT pour économiser de +l'espace}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Maintenant, construisez l'image de la manière habituelle: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Sur le système de l'auteur au moment de l'écriture, la configuration +ci-dessus produisait une image de 110 Mo. Cela se compare favorablement avec +l'image de 192 Mo produite par la configuration par défaut dans {Tutoriel +1}#tutorial-1. + +Laisser tomber les index d'APT avec #{--apt-indices false}# permet aussi +d'économiser une bonne quantité d'espace, le compromis étant que vous devez +faire #{apt-get update}# avant d'utiliser apt dans le système +live. Abandonner les paquets recommandés avec #{--apt-recommends false}# +économise de l'espace supplémentaire, au détriment de certains paquets dont +vous vous attendriez autrement qu'ils soient là. #{--debootstrap-options +"--variant=minbase"}# construit un système minimal dès le +début. L'utilisation de #{--firmware-chroot false}# n'inclut pas +automatiquement les paquets de micrologiciels. Finalement, #{--memtest +none}# prévient l'installation d'un testeur de mémoire. + +*{Remarque:}* Un système minimal peut également être obtenu en utilisant des hooks comme par exemple le #{stripped.hook.chroot}# dans #{/usr/share/doc/live-build/examples/hooks}#, il peut gagner de petites quantités supplémentaires d'espace et produire une image de 91 Mo. Cependant, il le fait par l'élimination de la documentation et d'autres fichiers des paquets installés sur le système. Cela porte atteinte à l'intégrité de ces paquets et, comme averti par le commentaire d'en-tête, cela peut avoir des conséquences imprévues. C'est pourquoi l'utilisation de /{debootstrap}/ est la méthode recommandée pour atteindre cet objectif. + +2~ Un bureau GNOME localisé avec un installateur + +*{Cas d'utilisation:}* Créer une image de bureau GNOME, localisée pour la Suisse et incluant un installateur. + +Nous voulons faire une image iso-hybrid pour l'architecture i386 en +utilisant notre bureau préféré, dans ce cas, GNOME, contenant tous les +paquets qui seraient installés par l'installateur Debian standard pour +GNOME. + +Notre premier problème est la découverte des noms des tâches +appropriées. Actuellement, live-build ne peut pas aider à faire cela. Alors +que nous pourrions être chanceux et trouver ces noms par essais et erreurs, +il existe un outil, #{grep-dctrl}#, qui peut être utilisé pour découvrir les +descriptions des tâches dans tasksel-data. Pour la préparation, assurez-vous +d'avoir ces deux outils: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Maintenant, nous pouvons rechercher les tâches appropriées, d'abord avec: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +Par cette commande, nous découvrons que la tâche est appelée, assez +clairement, german. Maintenant, pour trouver les tâches liées: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +Pendant le démarrage, nous allons générer la locale *{de_CH.UTF-8}* et +sélectionner la disposition de clavier *{ch}*. Maintenant, nous allons +mettre les morceaux ensemble. En nous rappelant grâce à {Utilisation des +métapaquets}#using-metapackages que les métapaquets sont préfixés #{task-}#, +nous précisons ces paramètres de la langue pendant l'amorçage, puis nous +ajoutons les paquets de priorité standard et tous nos métapaquets découverts +à notre liste de paquets comme suit: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Notez que nous avons inclus le paquet /{debian-installer-launcher}/ pour +lancer l'installateur à partir du bureau live. Le noyau #{586}#, qui est +actuellement nécessaire pour faire que le lanceur fonctionne correctement, +est inclus par défaut. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/fr/live-manual.ssm new file mode 100644 index 0000000..e6b7b78 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manuel Live Systems" + +creator: + author: "Projet Live Systems <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "Ce programme est un logiciel libre; vous pouvez le redistribuer ou le modifier suivant les termes de la Licence Générale Publique GNU telle que publiée par la Free Software Foundation: soit la version 3 de cette licence, soit (à votre gré) toute version ultérieure. \\ \\ Ce programme est distribué dans l’espoir qu’il vous sera utile, mais SANS AUCUNE GARANTIE: sans même la garantie implicite de COMMERCIALISABILITÉ ni d’ADÉQUATION À UN OBJECTIF PARTICULIER. Consultez la Licence Générale Publique GNU pour plus de détails. \\ \\ Vous devriez avoir reçu une copie de la Licence Générale Publique GNU avec ce programme ; si ce n’est pas le cas, consultez http://www.gnu.org/licenses/. \\ \\ Le texte complet de la Licence Générale Publique GNU peut être trouvé dans le fichier / usr/share/common-licenses/GPL-3" + +date: + published: "2015-08-23" + +publisher: "Projet Live Systems <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ À propos + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Utilisateur + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Projet + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Exemples + +<< examples.ssi + +:B~ Appendix + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/project_bugs.ssi new file mode 100644 index 0000000..4f785ca --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/project_bugs.ssi @@ -0,0 +1,223 @@ +:B~ Signaler des bogues + +1~bugs Signaler des bogues + +Les systèmes live sont loin d'être parfaits, mais nous voulons les rendre +aussi parfaits que possible − avec votre aide. N'hésitez pas à signaler un +bogue. Il est préférable de remplir un rapport deux fois plus que +jamais. Toutefois, ce chapitre contient des recommandations pour présenter +de bons rapports de bogues. + +Pour les impatients: + +_* Commencez toujours par vérifier les mises à jour du statut de l'image sur +notre page d'accueil http://live-systems.org/ pour voir les problèmes +connus. + +_* Avant de présenter un rapport de bogue, toujours essayer de reproduire +le bogue avec *{les versions les plus récentes}* de la branche de +live-build, live-boot, live-config et live-tools que vous utilisez (comme la +dernière version 4.x de live-build si vous utilisez live-build 4). + +_* Essayez de donner des informations aussi précises que possible sur le +bogue. Cela comprend (au moins) la version de live-build, live-boot, +live-config et live-tools, de la distribution utilisée et du système live +que vous construisez. + +2~ Problèmes connus + +Puisque les distributions Debian *{testing}* et Debian *{unstable}* sont des +cibles mouvantes, quand vous les indiquez comme distributions du système +cible, une construction avec succès n'est pas toujours possible. + +% FIXME: + +Si cela vous pose trop de difficulté, ne construisez pas un système basé sur +*{testing}* ou *{unstable}*, mais utilisez plutôt *{stable}*. live-build +utilise toujours la version *{stable}* par défaut. + +Les problèmes connus sont énumérés dans la section «statut» sur notre page +http://live-systems.org/. + +Le sujet de ce manuel n'est pas de vous former à identifier et corriger +correctement les problèmes dans les paquets des distributions de +développement. Cependant, il y a deux choses que vous pouvez toujours +essayer: Si une construction échoue lorsque la distribution cible est +*{testing}*, essayez *{unstable}*. Si *{unstable}* ne fonctionne pas non +plus, revenez à *{testing}* et fixez la nouvelle version du paquet qui +échoue de *{unstable}* (voir {APT pinning}#apt-pinning pour plus de +détails). + +2~ Reconstruire à partir de zéro + +Afin de vous assurer qu'un bogue en particulier n'est pas causé par un +système mal construit, veuillez toujours reconstruire l'ensemble du système +live à partir de zéro pour voir si le bogue est reproductible. + +2~ Utiliser des paquets mis à jour + +L'utilisation de paquets obsolètes peut causer des problèmes importants en +essayant de reproduire (et finalement régler) votre problème. Assurez-vous +que votre système de construction est mis à jour et tous les paquets inclus +dans votre image sont mis à jour aussi. + +2~collect-information Recueillir l'information + +Veuillez fournir assez d'informations avec votre rapport. Incluez au moins +la version exacte de live-build où le bogue est rencontré et les mesures +pour le reproduire. Veuillez utiliser votre bon sens et incluez d'autres +renseignements pertinents, si vous pensez que cela pourrait aider à résoudre +le problème. + +Pour tirer le meilleur parti de votre rapport de bogue, nous avons au moins +besoin des informations suivantes: + +_* L'architecture du système hôte + +_* Distribution du système hôte + +_* Version de live-build sur le système hôte + +_* Version de /{debootstrap}/ sur le système hôte + +_* L'architecture du système live + +_* Répartition du système live + +_* Version de live-boot sur le système live + +_* Version de live-config sur le système live + +_* Version de live-tools sur le système live + +Vous pouvez générer un journal du processus de construction en utilisant la +commande #{tee}#. Nous recommandons de faire cela automatiquement avec un +script #{auto/build}# (voir {Gestion d'une +configuration}#managing-a-configuration pour les détails). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Au démarrage, live-boot et live-config stockent un journal dans +#{/var/log/live/boot.log}#. Vérifiez-les pour des messages d'erreur. + +Par ailleurs, pour écarter d'autres erreurs, c'est toujours une bonne idée +de faire un tar de votre répertoire #{config/}# et de le télécharger quelque +part (*{ne pas}* l'envoyer en pièce jointe à la liste de diffusion), de +sorte que nous puissions essayer de reproduire les erreurs que vous +rencontrez. Si cela est difficile (en raison par exemple de la taille) vous +pouvez utiliser la sortie de #{lb config --dump}# qui produit un résumé de +votre arbre de config (c'est-à-dire les listes des fichiers dans les +sous-répertoires de #{config/}# mais ne les inclut pas). + +N'oubliez pas d'envoyer tous les journaux produits avec les paramètres +régionaux anglais. Par exemple, exécutez vos commandes live-build précédées +par #{LC_ALL=C}# ou #{LC_ALL=en_US}#. + +2~ Isoler le cas qui échoue, si possible + +Si possible, isolez le cas qui échoue au plus petit changement possible. Il +n'est pas toujours facile de faire cela, donc si vous ne pouvez pas le gérer +pour votre rapport, ne vous inquiétez pas. Toutefois, si vous planifiez +bienvotre cycle de développement, en utilisant de petits ensembles de +changements par itération, vous pourriez être capable d'isoler le problème +en construisant une configuration simple «base» qui correspond étroitement à +la configuration réelle avec seulement le changement cassé ajouté. S'il est +difficile de trier vos modifications qui cassent, il est possible que vous +incluiez trop dans chaque ensemble de modifications et vous devriez +développer en petits incréments. + +2~ Utiliser le paquet adéquat pour rapporter un bogue + +Si vous ne savez pas quel composant est responsable du bogue ou si le bogue +est un bogue général concernant les systèmes live, vous pouvez remplir un +rapport de bogue sur le pseudo-paquet debian-live. + +Toutefois, nous apprécierions que vous essayiez de le réduire en fonction de +l'endroit où le bogue apparaît. + +3~ Pendant la construction durant l'amorçage + +live-build amorce d'abord un système Debian de base avec /{debootstrap}/. Si +un bogue apparaît ici, vérifiez si l'erreur est liée à un paquet Debian +spécifique (plus probable), ou si elle est liée à l'outil d'amorçage +lui-même. + +Dans les deux cas, ce n'est pas un bogue dans le système live, mais plutôt +dans Debian lui-même que probablement nous ne pouvons pas le résoudre +directement. Veuillez signaler un bogue sur l'outil d'amorçage ou du paquet +défaillant. + +3~ Pendant la construction durant l'installation de paquets + +live-build installe des paquets supplémentaires de l'archive Debian et en +fonction de la distribution Debian utilisée et l'état quotidien de +l'archive, il peut échouer. Si un bogue apparaît ici, vérifiez si l'erreur +est également reproductible sur un système normal. + +Si c'est le cas, ce n'est pas un bogue dans le système live, mais plutôt +dans Debian − veuillez envoyer le rapport sur le paquet +défaillant. L'exécution de /{debootstrap}/ séparément du système de +construction ou l'exécution de #{lb bootstrap --debug}# vous donnera plus +d'informations. + +Aussi, si vous utilisez un miroir local et/ou un proxy et vous rencontrez un +problème, veuillez toujours le reproduire en amorçant d'abord sur un miroir +officiel. + +3~ Pendant le démarrage + +Si votre image ne démarre pas, veuillez le signaler à la liste de diffusion +avec les informations demandées dans {Recueillir +l'information}#collect-information. N'oubliez pas de mentionner, +comment/quand l'image a échoué, soit en virtualisation ou sur du matériel +réel. Si vous utilisez une technologie de virtualisation de quelconque +sorte, veuillez toujours tester sur du matériel réel avant de signaler un +bogue. Fournir une copie d'écran de l'échec est également très utile. + +3~ Pendant l'exécution + +Si un paquet a été installé avec succès, mais qu'il échoue lors de +l'exécution du système Live, il s'agit probablement d'un bogue dans le +système live. Cependant: + +2~ Effectuer une recherche + +Avant de présenter le bogue, veuillez rechercher sur le web le message +d'erreur ou un symptôme particulier que vous obtenez. Comme il est hautement +improbable que vous soyez la seule personne faisant l'expérience d'un +problème particulier, il y a toujours une chance qu'il ait été discuté +ailleurs, et qu'une solution possible, un correctif, ou une solution de +contournement ait été proposés. + +Vous devez prêter une attention particulière à la liste de diffusion du +système live, ainsi qu'à la page d'accueil, car elles sont susceptibles de +contenir des informations à jour. Si ces informations existent, incluez +toujours les références au sein de vos rapports de bogues. + +En outre, vous devriez vérifier les listes de bogues en cours de live-build, +live-boot, live-config et live-tools pour voir si quelque chose de +semblable n'a pas déjà été signalée. + +2~ Où rapporter les bogues + +Le ${project} conserve la trace de tous les bogues dans le système de suivi +des bogues (BTS). Pour plus d'informations sur la façon d'utiliser le +système, veuillez consulter https://bugs.debian.org/. Vous pouvez également +soumettre les bogues en utilisant la commande #{reportbug}# du paquet du +même nom. + +En général, vous devez signaler les erreurs de construction contre le paquet +live-build, les erreurs lors du démarrage contre live-boot, et les erreurs +d'exécution contre live-config. Si vous n'êtes pas sûr du paquet approprié +ou si vous avez besoin d'aide avant de soumettre un rapport de bogue, +veuillez signaler le bogue contre le pseudo-paquet debian-live. Nous le +réattribuerons s'il y a lieu. + +Veuillez noter que les bogues trouvés dans les distributions dérivées de +Debian (comme Ubuntu et autres) *{ne}* doivent *{pas}* être rapportés au BTS +de Debian, sauf s'ils peuvent être également reproduits sur un système +Debian en utilisant les paquets Debian officiels. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/project_coding-style.ssi new file mode 100644 index 0000000..9f42294 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/project_coding-style.ssi @@ -0,0 +1,154 @@ +:B~ Style de code + +1~coding-style Style du code + +Ce chapitre documente le style du code utilisé dans les systèmes live. + +2~ Compatibilité + +_* N'utilisez pas une syntaxe ou sémantique qui soit unique au shell +Bash. Par exemple, l'utilisation de tableaux (arrays). + +_* N'utilisez que le sous-ensemble POSIX − par exemple, utilisez $(foo) au +lieu de `foo`. + +_* Vous pouvez vérifier vos scripts avec 'sh -n' et 'checkbashisms'. + +_* Assurez-vous que tout le code fonctionne avec 'set-e '. + +2~ Indentation + +_* Utilisez toujours des tabulations au lieu des espaces. + +2~ Adaptateur + +_* Généralement, les lignes sont de 80 caractères au maximum. + +_* Utilisez le «style Linux» des sauts de ligne: + +Mal: + +code{ + + if foo; then + bar + fi + +}code + +Bien: + +code{ + + if foo + then + bar + fi + +}code + +_* La même chose vaut pour les fonctions: + +Mal: + +code{ + + Foo () { + bar + } + +}code + +Bien: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Les variables sont toujours en lettres majuscules. + +_* Les variables utilisées dans live-build commencent toujours par le +préfixe #{LB_}#. + +_* Les variables temporaires internes dans live-build devraient commencer +avec le préfixe #{\_LB_}#. + +_* Les variables locales commencent avec le préfixe #{\_\_LB_}#. + +_* Les variables en relation avec un paramètre de démarrage dans live-config +commencent par #{LIVE_}#. + +_* Toutes les autres variables dans live-config commencent par le préfixe +#{_}#. + +_* Utilisez des accolades autour des variables; écrivez par exemple +#{${FOO}}# au lieu de #{$FOO}#. + +_* Protégez toujours les variables avec des guillemets pour respecter les +espaces potentiels: écrire #{"${FOO}"}# en lieu de #{${FOO}}#. + +_* Pour des raisons de cohérence, utilisez toujours les guillemets lors de +l'attribution des valeurs aux variables: + +Mal: + +code{ + + FOO=bar + +}code + +Bien: + +code{ + + FOO="bar" + +}code + +_* Si plusieurs variables sont utilisées, utilisez les guillemets pour +l'expression complète: + +Mal: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Bien: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Autres + +_* Utilisez "#{|}#" (sans les guillemets autour) comme séparateur dans les +appels à sed, par exemple "#{sed -e 's|foo|bar|'}#" (sans" "). + +_* N'utilisez pas la commande #{test}# pour des comparaisons ou des tests, +utilisez "#{[}#" "#{]}#" (sans ""); par exemple "#{if [ -x /bin/foo ]; +...}#" et non pas "#{if test -x /bin/foo; ...}#". + +_* Utilisez #{case}# dans la mesure du possible au lieu de #{test}#, parce +qu'il est plus facile à lire et plus rapide à exécuter. + +_* Utilisez des noms en majuscule pour les fonctions pour éviter toute +interférence avec l'environnement des utilisateurs. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/project_contributing.ssi new file mode 100644 index 0000000..60a90cd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/project_contributing.ssi @@ -0,0 +1,119 @@ +:B~ Contribuer au projet + +1~contributing-to-project Contribuer au projet + +Lorsque vous soumettez une contribution, veuillez indiquer clairement le +copyright et inclure toute mention légale relative à la licence. Notez que +pour être acceptée, la contribution doit être déposée sous la même licence +que le reste du document, c'est-à-dire la GPL version 3 ou ultérieure. + +Les contributions au projet, comme les traductions et les correctifs, sont +bienvenues. Les livraisons au dépôt sont possibles pour tout le monde, +cependant, nous vous demandons d'envoyer les changements importants sur la +liste de diffusion au préalable. Veuillez consulter {Contacter}#contact pour +plus d'informations. + +Le ${project} utilise Git en tant que système de contrôle de version et de +gestion du code source. Comme expliqué dans {Dépôts Git}#git-repositories il +existe deux branches de développement principales: *{debian}* et +*{debian-next}*. Tout le monde peut faire des livraisons aux branches +debian-next des dépôts live-boot, live-build, live-config, live-images, +live-manual et live-tools. + +Cependant, il y a certaines restrictions. Le serveur rejette: + +_* Push non fast-forward. + +_* Commits merge. + +_* Ajout ou suppression d'étiquettes ou des branches. + +Même si toutes les livraisons pourraient être révisées, nous vous demandons +d'utiliser votre bon sens et de faire bonnes livraisons avec de bons +messages de livraison. + +_* Veuillez écrire les commentaires de livraison à l'aide de phrases +complètes, en commençant par une majuscule et en terminant par un point, et +avec la forme 'Fixing/Adding/Removing/Correcting/Translating/...'. + +_* Écrivez de bons messages de livraison. La première ligne doit être un +résumé précis du contenu du commit qui sera inclus dans le changelog. Si +vous avez besoin de faire quelques explications supplémentaires, écrivez-les +au-dessous en laissant une ligne vide après la première, puis une autre +ligne vide après chaque paragraphe. Les lignes des paragraphes ne doivent +pas dépasser 80 caractères. + +_* Faites des livraisons de façon atomique, c'est-à-dire, ne mélangez pas +des choses sans liens entre elles dans la même livraison. Faites un commit +différent pour chaque modification que vous apportez. + +2~ Faire des changements + +Afin de faire un push sur les dépôts, vous devez suivre la procédure +suivante. Ici, nous utilisons live-manual comme un exemple pour le remplacer +par le nom du dépôt dans lequel vous souhaitez travailler. Pour plus +d'informations sur la façon de modifier live-manual, consultez {Contribuer à +ce document}#how-to-contribute. + +_* Téléchargez la clé publique: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Ajoutez la section suivante à votre configuration openssh-client: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Clonez live-manual avec ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Assurez-vous d'avoir renseignés les champs d'auteur et d'email dans Git: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Important:}* Rappelez-vous que vous devez livrer les changements sur la branche *{debian-next}*. + +_* Effectuez vos modifications. Dans cet exemple, vous devriez commencer par +écrire une nouvelle section traitant l'application des correctifs et ensuite +préparer l'ajout des fichiers et écrire le message de livraison comme ceci: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Envoyez votre commit au serveur: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/project_git.ssi new file mode 100644 index 0000000..e095175 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/project_git.ssi @@ -0,0 +1,88 @@ +:B~ Dépôts Git + +1~git-repositories Dépôts Git + +La liste de tous les dépôts disponibles du ${project} est sur +http://live-systems.org/gitweb/. Les URLs git du projet ont la forme: +#{protocole://live-systems.org/git/dépôt}#. Ainsi, afin de cloner +live-manual en lecture seule, lancer: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Ou, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Ou, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +Les adresses pour cloner avec autorisation d'écriture ont la forme: +#{git@live-systems.org:/dépôt}#. + +Donc, encore une fois, pour cloner live-manual sur ssh, vous devez taper: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +L'arbre git est composé de plusieurs branches différentes. Les branches +*{debian}* et *{debian-next}* sont particulièrement remarquables car elles +contiennent le travail réel qui sera finalement inclus dans chaque nouvelle +version. + +Après avoir cloné quelques-uns des dépôts existants, vous serez sur la +branche *{debian}*. Ceci est approprié pour jeter un œil à l'état de la +dernière version du projet, mais avant de commencer le travail, il est +essentiel de passer à la branche *{debian-next}*. Pour ce faire: + +code{ + + $ git checkout debian-next + +}code + +La branche *{debian-next}*, qui n'est pas toujours fast-forward, est +l'endroit où toutes les modifications sont envoyées en premier, avant de les +fusionner dans la branche *{debian}*. Pour faire une analogie, c'est comme +un terrain d'essai. Si vous travaillez sur cette branche et avez besoin de +faire un pull, vous devrez faire un #{git pull --rebase}# de sorte que vos +modifications locales sont stockées tandis qu'on fait une mise à jour à +partir du serveur, puis vos changements seront mis au-dessus de tout cela. + +2~ Gestion de multiples dépôts + +Si vous avez l'intention de cloner plusieurs des dépôts Live Systems et +passer à la branche *{debian-next}* tout de suite pour vérifier le dernier +code, écrire un correctif ou contribuer avec une traduction, vous devriez +savoir que le serveur git fournit un fichier #{mrconfig}# pour faciliter la +manipulation de multiples dépôts. Pour l'utiliser, vous devez installer le +paquet /{mr}/, puis lancer: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +Cette commande va automatiquement cloner et passer à la branche +*{debian-next}* les dépôts de développement des paquets Debian produits par +le projet. Ceux-ci comprennent, entre autres, le dépôt live-images, qui +contient les configurations utilisées pour les images précompilées que le +projet publie pour un usage général. Pour plus d'informations sur la façon +d'utiliser ce dépôt, voir {Cloner une configuration publiée via +Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/project_procedures.ssi new file mode 100644 index 0000000..c1a2823 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/project_procedures.ssi @@ -0,0 +1,103 @@ +:B~ Procédures + +1~procedures Procédures + +Ce chapitre documente les procédures au sein du ${project} pour différentes +tâches qui ont besoin de coopération avec d'autres équipes dans Debian. + +2~ Évolutions majeures + +La libération d'une nouvelle version stable majeure de Debian inclut un +grand nombre de différentes équipes travaillant ensemble. À un certain +point, l'équipe Live arrive et construit des images du système live. Les +conditions pour ce faire sont les suivantes: + +_* Un miroir contenant les versions publiées des archives Debian et +debian-security auxquelles le buildd de debian-live peut avoir accès. + +_* Les noms de l'image doivent être connus (par exemple +debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* Les données qui proviennent de debian-cd doivent être synchronisées (udeb +exclude lists). + +_* Les images sont construites et mises en miroir sur cdimage.debian.org. + +2~ Évolutions mineures + +_* Encore une fois, nous avons besoin de miroirs de Debian et +Debian-security mis à jour. + +_* Les images sont construites et mises en miroir sur cdimage.debian.org. + +_* Envoyer un courriel d'annonce. + +3~ Dernière évolution mineure d'une version Debian + +N'oubliez pas de régler à la fois les miroirs pour chroot et binary lors de +la construction de la dernière série d'images pour une version de Debian +après qu'elle ait été déplacée de ftp.debian.org vers archive.debian.org. De +cette façon, les vieilles images live précompilées sont encore utiles, sans +modifications des utilisateurs. + +3~ Modèle pour l'annonce d'une évolution mineure + +Un courriel pour l'annonce d'une évolutioun mineure peut être généré en +utilisant le modèle ci-dessous et la commande suivante: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Veuillez vérifier le courriel avant l'envoi et le passer à d'autres pour la +relecture. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_basics.ssi new file mode 100644 index 0000000..ee671db --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_basics.ssi @@ -0,0 +1,674 @@ +:B~ Les bases + +1~the-basics Les bases + +Ce chapitre contient un bref aperçu du processus de construction et des +instructions pour utiliser les trois types d'images les plus couramment +utilisées. Le type d'image le plus polyvalent, #{iso-hybrid}#, peut être +utilisé sur une machine virtuelle, un support optique ou un périphérique USB +de stockage portable. Dans certains cas particuliers, comme expliqué plus +loin, le type #{hdd}# peut être plus approprié. Le chapitre contient des +instructions détaillées pour la construction et l'utilisation d'une image +#{netboot}#, qui est un peu plus compliquée en raison de la configuration +requise sur le serveur. C'est un sujet un peu avancé pour tous ceux qui ne +connaissent pas déjà le démarrage sur le réseau, mais est inclus ici car une +fois la configuration terminée, c'est un moyen très pratique pour tester et +déployer des images pour le démarrage sur le réseau local sans le tracas des +supports d'images. + +La section se termine par une brève introduction à webbooting qui est, +peut-être, la meilleure façon d'utiliser des images différentes à des fins +différentes, changeant de l'un à l'autre en fonction des besoins en +utilisant l'Internet comme un moyen. + +Tout au long du chapitre, nous ferons souvent référence à la valeur par +défaut des noms des fichiers produits par live-build. Si vous {téléchargez +une image précompilée}#downloading-prebuilt-images, les noms des fichiers +peuvent varier. + +2~what-is-live Qu'est-ce qu'un système live? + +Un système live signifie généralement un système d'exploitation démarré sur +un ordinateur à partir d'un support amovible, tel qu'un CD-ROM, une clé USB +ou sur un réseau, prêt à l'emploi sans aucune installation sur le disque +habituel, avec auto-configuration fait lors de l'exécution (voir +{Termes}#terms). + +Avec les systèmes live, c'est un système d'exploitation, construit pour une +des architectures prises en charge (actuellement amd64 et i386). Il est fait +à partir des éléments suivants: + +_* *{Image du noyau Linux}*, d'habitude appelé #{vmlinuz*}# + +_* *{Image du RAM-disque initiale (initrd)}*: Un disque virtuel RAM +configuré pour le démarrage de Linux, contenant possiblement des modules +nécessaires pour monter l'image du système et certains scripts pour le +faire. + +_* *{Image du système}*: L'image du système de fichiers du système +d'exploitation. Habituellement, un système de fichiers SquashFS comprimé est +utilisé pour réduire au minimum la taille de l'image live. Notez qu'il est +en lecture seulement. Ainsi, lors du démarrage le système live va utiliser +un disque RAM et un mécanisme "union" pour permettre l'écriture de fichiers +dans le système en marche. Cependant, toutes les modifications seront +perdues lors de l'arrêt à moins que l'option «persistance» soit utilisée +(voir {Persistance}#persistence). + +_* *{Chargeur d'amorçage}*: Un petit morceau de code conçu pour démarrer à +partir du support choisi, il peut présenter un menu rapide ou permettre la +sélection des options/configurations. Il charge le noyau Linux et son initrd +pour fonctionner avec un système de fichiers associé. Différentes solutions +peuvent être utilisées, selon le support de destination et le format du +système de fichiers contenant les composants mentionnés précédemment: +isolinux pour démarrer à partir d'un CD ou DVD au format ISO9660, syslinux +pour démarrer un disque dur ou une clé USB à partir d'une partition VFAT, +extlinux pour partitions ext2/3/4 et btrfs, pxelinux pour netboot PXE, GRUB +pour partitions ext2/3/4, etc. + +Vous pouvez utiliser live-build pour construire l'image du système à partir +de vos spécifications, configurer un noyau Linux, son initrd, et un chargeur +d'amorçage pour les exécuter, tout dans un format en fonction du support +(image ISO9660, image disque, etc.). + +2~downloading-prebuilt-images Téléchargement des images précompilées + +Bien que l'objectif de ce manuel soit le développement et la création de vos +propres images live, vous pouvez simplement vouloir tester une de nos images +précompilées comme une introduction à leur utilisation ou à la construction +de vos propres images. Ces images sont construites à l'aide de notre {dépôt +git live-images}#clone-configuration-via-git et les versions officielles +stables sont publiées sur https://www.debian.org/CD/live/. En outre, les +versions plus anciennes et les futures, et des images non officielles +contenant micrologiciels et pilotes non libres sont disponibles sur +http://live-systems.org/cdimage/release/. + +2~using-web-builder Utiliser le constructeur web d'images live + +En tant que service à la communauté, nous gérons un service de construction +d'images web sur http://live-systems.org/build/. Ce site est maintenu sur la +base du meilleur effort. Autrement dit, même si nous nous efforçons de le +maintenir à jour et opérationnel à tout moment, et de publier des avis +d'importantes interruptions du service, nous ne pouvons pas garantir une +disponibilité de 100% ou des constructions d'images rapides, et le service +peut parfois avoir des problèmes dont la résolution prend un certain +temps. Si vous avez des problèmes ou des questions au sujet du service, +veuillez {nous contacter}#contact en donnant le lien vers votre +construction. + +3~ Utilisation du constructeur web et avertissements + +L'interface web ne permet actuellement pas d'empêcher l'utilisation de +combinaisons d'options invalides, en particulier quand le changement d'une +option (c'est-à-dire en utilisant live-build directement) modifie les +valeurs des autres options énumérées dans le formulaire web, le constructeur +web ne modifie pas ces valeurs par défaut. Plus particulièrement, si vous +changez la valeur #{--architectures}# qui est par défaut #{i386}# pour +#{amd64}#, vous devez modifier l'option correspondante #{--linux-flavours}# +de la valeur par défaut #{586}# pour #{amd64}#. Voir la page de manuel +#{lb_config}# pour la version de live-build installée sur le constructeur +web pour plus de détails. Le numéro de version de live-build est indiqué au +bas de la page web. + +L'estimation du temps donné par le constructeur web est une estimation brute +et peut ne pas refléter la durée effective de votre construction. Cette +estimation n'est pas actualisée une fois qu'elle est affichée. Soyez +patient. Ne rechargez pas la page de la construction, car cela peut +soumettre une nouvelle construction avec les mêmes paramètres. Vous devez +{nous contacter}#contact si vous ne recevez pas la notification de votre +construction mais seulement une fois que vous êtes sûr que vous avez attendu +assez longtemps et vérifié que la notification par e-mail n'a pas été +détectée par votre filtre anti-spam. + +Le constructeur web est limité dans les types d'images qu'il peut +construire. Cela permet de garder les choses simples et efficaces à utiliser +et à maintenir. Si vous souhaitez effectuer des personnalisations qui ne +sont pas prévues par l'interface web, le reste de ce manuel explique comment +construire vos propres images en utilisant live-build. + +2~building-iso-hybrid Premières étapes: la construction d'une image ISO +hybride + +Quel que soit le type d'image, vous devrez effectuer les mêmes étapes de +base pour créer une image à chaque fois. Comme premier exemple, créez un +répertoire de travail, passez dans ce répertoire et exécutez la séquence +suivante de commandes live-build pour créer une image ISO hybride de base +contenant tout le système Debian par défaut sans X.org. Elle est appropriée +pour être gravée sur CD ou DVD, et peut également être copiée sur une clé +USB. + +Le nom du répertoire de travail dépend totalement de vous, mais si vous +jetez un œil aux exemples utilisés dans live-manual, c'est une bonne idée +d'utiliser un nom qui vous aide à identifier l'image avec laquelle vous +travaillez dans chaque répertoire, surtout si vous travaillez ou +expérimentez avec différents types d'images. Dans ce cas, vous allez +construire un système par défaut, nous allons donc l'appeler, par exemple, +live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Ensuite, exécutez la commande #{lb config}#. Cela va créer une hiérarchie +"config/" dans le répertoire courant pour être utilisée par d'autres +commandes: + +code{ + + $ lb config + +}code + +Aucun paramètre n'est passé à ces commandes, donc les défauts seront +utilisés pour l'ensemble de ses diverses options. Consultez {La commande lb +config}#lb-config pour plus de détails. + +Maintenant que la hiérarchie "config/" existe, créez l'image avec la +commande #{lb build}# : + +code{ + + # lb build + +}code + +Ce processus peut prendre un certain temps, en fonction de la vitesse de +votre ordinateur et de votre connexion réseau. Une fois le processus +terminé, il devrait y avoir un fichier image #{live-image-i386.hybrid.iso}# +prêt à l'emploi, dans le répertoire courant. + +*{Remarque:}* Si vous construisez sur un système amd64 le nom de l'image résultante sera #{live-image-amd64.hybrid.iso}#. Gardez à l'esprit cette convention de nommage tout au long du manuel. + +2~using-iso-hybrid Utilisation d'une image ISO hybride live + +Après la construction ou le téléchargement d'une image ISO hybride, qui peut +être obtenue sur https://www.debian.org/CD/live/, l'étape suivante est +d'habitude de préparer votre support pour le démarrage, soit sur CD-R(W) ou +DVD-R(W), des supports optiques ou une clé USB. + +3~burning-iso-image Graver une image ISO sur un support physique + +Graver une image ISO est facile. Il suffit d'installer /{xorriso} et de +l'utiliser à partir de la ligne de commande pour graver l'image. Par +exemple: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copie d'une image ISO hybride sur une clé USB + +Les images ISO préparées avec #{xorriso}# peuvent être simplement copiées +sur une clé USB avec #{cp}# ou un logiciel équivalent. Branchez une clé USB +avec une capacité suffisamment grande pour votre fichier image et déterminez +quel périphérique elle est, que nous appelons ci-dessous +#{${USBSTICK}}#. C'est le fichier de périphérique de votre clé, tel que +#{/dev/sdb}#, pas une partition, telle que #{/dev/sdb1}#! Vous pouvez +trouver le nom du périphérique en regardant la sortie de #{dmesg}# après +avoir branché le périphérique, ou mieux encore, #{ls -l /dev/disk/by-id}#. + +Une fois que vous êtes sûr d'avoir le nom correct de l'appareil, utilisez la +commande #{cp}# pour copier l'image sur la clé. *{Ceci écrasera tout fichier +déjà existant sur votre clé!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Remarque:}* La commande /{sync}/ est utilisée pour s'assurer que toutes les données qui sont stockées dans la mémoire par le noyau lors de la copie de l'image, sont écrites sur la clé USB. + +3~using-usb-extra-space Utilisation de l'espace disponible sur une clé USB + +Après avoir copié #{live-image-i386.hybrid.iso}# sur une clé USB, la +première partition sera utilisée par le système live. Pour utiliser l'espace +libre restant, utilisez un outil de partitionnement tel que /{gparted}/ ou +/{parted}/ afin de créer une nouvelle partition sur la clé. + +code{ + + # gparted ${USBSTICK} + +}code + +Quand la partition est créée, vous devez y créer un système de fichiers où +#{${PARTITION}}# est le nom de la partition, comme #{/dev/sdb2}#. Un choix +possible serait ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Remarque:}* Si vous voulez utiliser l'espace supplémentaire avec Windows, ce système d’exploitation ne peut accéder normalement à aucune partition à part la première. Certaines solutions à ce problème ont été discutées sur notre {liste de diffusion}#contact, mais il semble qu'il n'y a pas de réponse facile. + +*{Rappelez-vous: Chaque fois que vous installez une nouvelle live-image-i386.hybrid.iso sur la clé, toutes les données sur la clé seront perdues parce que la table de partition est écrasée par le contenu de l'image, vous devez sauvegarder votre partition supplémentaire d'abord pour la restaurer à nouveau après la mise à jour de l'image live.}* + +3~booting-live-medium Démarrer le support live + +La première fois que vous démarrez votre support live, qu'il s'agisse de CD, +DVD, clé USB, ou du démarrage par PXE, une certaine configuration dans le +BIOS de votre ordinateur peut être d'abord nécessaire. Puisque les BIOS +varient grandement en fonctionnalités et raccourcis clavier, on ne peut pas +aborder le sujet en profondeur ici. Certains BIOS fournissent une touche +pour ouvrir un menu d'amorçage au démarrage, qui est le moyen le plus facile +si elle est disponible sur votre système. Sinon, vous avez besoin d'entrer +dans le menu de configuration du BIOS et modifier l'ordre de démarrage pour +placer le dispositif de démarrage pour le système live devant votre +périphérique de démarrage normal. + +Une fois que vous avez démarré le support, un menu de démarrage vous est +présenté. Si vous appuyez simplement sur entrée ici, le système va démarrer +en utilisant l'entrée par défaut, #{Live}#. Pour plus d'informations sur les +options de démarrage, consultez l'entrée «Help» dans le menu et aussi les +pages de manuel de live-boot et live-config dans le système live. + +En supposant que vous ayez sélectionné #{Live}# et démarré une image de +bureau live par défaut, après que les messages de démarrage aient défilé, +vous devriez être automatiquement connecté au compte #{user}# et voir un +bureau, prêt à l'emploi. Si vous avez démarré une image de la console +uniquement, tel que le type #{standard}# des {images +précompilées}#downloading-prebuilt-images, vous devriez être automatiquement +connecté à la console pour le compte #{user}# et voir une invite du shell, +prête à l'emploi. + +2~using-virtual-machine Utiliser une machine virtuelle pour les tests + +Exécuter les images live dans une machine virtuelle (VM) peut faire gagner +beaucoup de temps. Cela ne vient pas sans avertissements: + +_* L'exécution d'une VM demande assez de RAM pour le système d’exploitation +client et l'hôte et un CPU avec support matériel pour la virtualisation est +recommandé. + +_* Il y a quelques limitations inhérentes à l'exécution sur une VM, par +exemple des performances vidéo médiocres, ou un choix limité de matériel +émulé. + +_* Lors du développement d'un matériel spécifique, il n'existe aucun +substitut pour l'exécution que le matériel lui-même. + +_* Certains ne deviennent visibles que pendant l'exécution dans une VM. En +cas de doute, testez votre image directement sur le matériel. + +À condition de pouvoir travailler avec ces contraintes, examinez les +logiciels VM disponibles et choisissez celui qui convient à vos besoins. + +3~testing-iso-with-qemu Test d'une image ISO avec QEMU + +La VM la plus polyvalente de Debian est QEMU. Si votre processeur dispose +d'une gestion matérielle de la virtualisation, vous pouvez utiliser le +paquet /{qemu-kvm}/; La description du paquet /{qemu-kvm}/ énumère +brièvement les exigences. + +Tout d'abord, installez /{qemu-kvm}/ si votre processeur le gère. Sinon, +installez /{qemu}/. Dans ce cas, le nom du programme est #{qemu}# au lieu de +#{kvm}# dans les exemples suivants. Le paquet /{qemu-utils}/ est également +valable pour créer des images de disques virtuels avec #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Démarrer une image ISO est simple: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +Voir les pages de manuel pour plus de détails. + +3~testing-iso-with-virtualbox Test d'une image ISO avec VirtualBox + +Afin de tester l'ISO avec /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Créez une nouvelle machine virtuelle, modifiez les paramètres de stockage +pour utiliser #{live-image-i386.hybrid.iso}# comme le périphérique CD/DVD et +démarrez la machine. + +*{Remarque:}* Pour les systèmes live contenant X.org que vous voulez essayer avec /{virtualbox}/, vous pouvez inclure le paquet des pilotes VirtualBox X.org, /{virtualbox-guest-dkms}/ et /{virtualbox-guest-x11}/, dans votre configuration de live-build. Sinon, la résolution est limitée à 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +Pour faire fonctionner le paquet dmks, il faut également installer le paquet +linux-headers pour le noyau utilisé dans l'image. Au lieu de lister +manuellement le paquet /{linux-headers}/ correct dans la liste de paquets +crée ci-dessus, live-build peut faire cela automatiquement. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Construire et utiliser une image HDD + +La construction d'une image HDD est similaire à une ISO hybride à tous les +regards, sauf que vous spécifiez #{-b hdd}# et le nom du fichier résultant +est #{live-image-i386.img}# qui ne peut être gravé sur des supports +optiques. Il convient pour le démarrage à partir de clés USB, disques durs +USB, et divers autres dispositifs de stockage portables. Normalement, une +image ISO hybride peut être utilisée à cette fin, mais si vous avez un BIOS +qui ne gère pas correctement les images hybrides, vous devez utiliser une +image HDD. + +*{Remarque:}* si vous avez créé une image ISO hybride avec l'exemple précédent, vous devrez nettoyer votre répertoire de travail avec la commande #{lb clean}# (voir {La commande lb clean}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Exécutez la commande #{lb config}# comme avant, sauf que cette fois en +spécifiant le type d'image HDD: + +code{ + + $ lb config -b hdd + +}code + +Construisez maintenant l'image avec la commande #{lb build}# + +code{ + + # lb build + +}code + +Quand la création de l'image est finie, un fichier #{live-image-i386.img}# +doit être présent dans le répertoire courant. + +L'image binaire générée contient une partition VFAT et le chargeur +d'amorçage syslinux, prêts à être écrits directement sur une clé USB. Encore +une fois, comme l'utilisation d'une image HDD est juste comme l'utilisation +d'une image ISO hybride sur USB, suivez les instructions {Utiliser une image +live ISO hybride}#using-iso-hybrid, en utilisant le nom de fichier +#{live-image-i386.img}# au lieu de #{live-image-i386.hybrid.iso}#. + +De même, pour tester une image HDD avec Qemu, installez /{qemu}/ comme +décrit ci-dessus dans {Test d'une image ISO avec +QEMU}#testing-iso-with-qemu. Ensuite, exécutez #{kvm}# ou #{qemu}#, selon la +version dont votre système hôte a besoin en précisant +#{live-image-i386.img}# comme le premier disque dur. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Construction d'une image netboot + +La séquence de commandes suivante va créer une image NetBoot de base +contenant le système Debian par défaut sans X.org. Elle peut être démarrée +sur le réseau. + +*{Remarque:}* Si vous avez réalisé quelques-uns des exemples précédents, vous aurez besoin de nettoyer votre répertoire de travail avec la commande #{lb clean}#: + +code{ + + # lb clean + +}code + +Dans ce cas spécifique, un #{lb clean --binary}# ne serait pas suffisant +pour nettoyer les étapes nécessaires. La raison est que dans les +configurations de netboot, une configuration initramfs différente doit être +utilisée, laquelle live-build exécute automatiquement lors de la +construction des images netboot. Puisque la création d'initramfs appartient +à l'étape chroot, si on change à netboot dans un répertoire existant, il +faut reconstruire le chroot. Par conséquent, il faut faire un #{lb clean}#, +(qui permettra d'éliminer l'étape chroot, aussi). + +Exécutez la commande suivante pour configurer votre image pour démarrer sur +le réseau: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +Contrairement aux images ISO et HDD, le démarrage sur le réseau ne sert pas +l'image du système de fichiers pour le client. Pour cette raison, les +fichiers doivent être servis via NFS. Différents systèmes de fichiers réseau +peuvent être choisis avec lb config. Les options #{--net-root-path}# et +#{--net-root-server}# indiquent l'emplacement et le serveur, respectivement, +du serveur NFS sur lequel l'image du système de fichiers sera située au +moment du démarrage. Assurez-vous que ceux-ci sont fixées à des valeurs +appropriées pour votre réseau et serveur. + +Construisez maintenant l'image avec la commande #{lb build}# + +code{ + + # lb build + +}code + +Dans un démarrage réseau, le client exécute un petit morceau de logiciel qui +réside habituellement sur l'EPROM de la carte Ethernet. Ce programme envoie +une requête DHCP pour obtenir une adresse IP et les informations sur ce +qu'il faut faire ensuite. Typiquement, la prochaine étape est d'obtenir un +chargeur d'amorçage de niveau supérieur via le protocole TFTP. Cela pourrait +être pxelinux, GRUB, ou démarrer directement à un système d'exploitation +comme Linux. + +Par exemple, si vous décompressez l'archive généré +#{live-image-i386.netboot.tar}# dans le répertoire #{/srv/debian-live}#, +vous trouverez l'image du système de fichiers dans +#{live/filesystem.squashfs}# et le noyau, initrd et le chargeur d'amorçage +pxelinux dans #{tftpboot/}#. + +Nous devons maintenant configurer trois services sur le serveur pour activer +le démarrage sur le réseau: le serveur DHCP, le serveur TFTP et le serveur +NFS. + +3~ Serveur DHCP + +Nous devons configurer le serveur DHCP de notre réseau pour être sûr de +donner une adresse IP au client du système du démarrage sur le réseau, et +pour annoncer l'emplacement du chargeur d'amorçage PXE. + +Voici un exemple source d'inspiration, écrit pour le serveur ISC DHCP +#{isc-dhcp-server}# dans le fichier de configuration +#{/etc/dhcp/dhcpd.conf}#: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Serveur TFTP + +Cela sert le noyau et le ramdisk initial pour le système pendant +l'exécution. + +Vous devriez installer le paquet /{tftpd-hpa}/. Il peut servir tous les +fichiers contenus dans un répertoire racine, d'habitude #{/srv/tftp}#. Pour +le laisser servir des fichiers dans #{/srv/debian-live/tftpboot}#, exécutez +comme utilisateur root la commande suivante: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +et remplissez le nouveau répertoire du serveur tftp + +3~ Serveur NFS + +Quand l'ordinateur hôte a téléchargé et démarré un noyau Linux et chargé son +initrd, il va essayer de monter l'image du système de fichiers live via un +serveur NFS. + +Vous devez installer le paquet /{nfs-kernel-server}/. + +Ensuite, rendez l'image du système de fichiers disponible via NFS en +ajoutant une ligne comme la suivante #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +et indiquez cette exportation au serveur NFS avec la commande suivante: + +code{ + + # exportfs -rv + +}code + +La configuation de ces trois services peut être un peu dificile. Vous +pourriez avoir besoin de patience pour obtenir que tous fonctionnent +ensemble. Pour plus d'informations, consultez le wiki syslinux sur +http://www.syslinux.org/wiki/index.php/PXELINUX ou la section Debian +Installer Manual's TFTP Net Booting sur +http://d-i.alioth.debian.org/manual/fr.i386/ch04s05.html. Ils pourraient +aider parce que leurs processus sont très semblables. + +3~ Guide pratique pour expérimenter avec une image Netboot + +La création d'images netboot est facile avec live-build, mais les tests des +images sur des machines physiques peuvent prendre vraiment beaucoup de +temps. + +Afin de rendre notre vie plus facile, nous pouvons utiliser la +virtualisation. + +3~ Qemu + +_* Installer /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Éditer #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Obtenir, ou construire un #{grub-floppy-netboot}#. + +Lancer #{qemu}# avec "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting est une manière très pratique de télécharger et d'amorcer les +systèmes live en utilisant l'Internet comme un moyen. Il ya très peu +d'exigences pour webbooting. D'une part, vous avez besoin d'un support avec +un chargeur d'amorçage, un disque ram initial et un noyau. D'autre part, un +serveur web pour stocker les fichiers squashfs qui contiennent le système de +fichiers. + +3~ Obtenir les fichiers webboot + +Comme d'habitude, vous pouvez construire les images vous-même ou utiliser +les fichiers précompilés, qui sont disponibles sur le site du projet sur +http://live-systems.org/. L'utilisation des images précompilées serait +pratique pour faire l'essai initial jusqu'à ce que l'on peut affiner leurs +propres besoins. Si vous avez construit une image live, vous trouverez les +fichiers nécessaires pour webbooting dans le répertoire de construction sous +#{binary/live/}#. Les fichiers sont appelés #{vmlinuz}#, #{initrd.img}# et +#{filesystem.squashfs}#. + +Il est également possible d'extraire les fichiers d'une image iso déjà +existant. Pour ce faire, on doit monter l'image comme suit: + +code{ + + # mount -o loop image.iso /mnt + +}code + +Les fichiers se trouvent sous le répertoire #{live/}#. Dans ce cas précis, +il serait #{/mnt/live/}#. Cette méthode présente l'inconvénient que vous +avez besoin d'être root pour pouvoir monter l'image. Cependant, il présente +l'avantage qu'elle est facilement scriptable et ainsi, facilement +automatisée. + +Mais sans aucun doute, la meilleure façon d'extraire les fichiers d'une +image iso et les télécharger sur le serveur web au même temps, est +d'utiliser le midnight commander ou /{mc}/. Si vous avez le paquet +/{genisoimage}/ installé, le gestionnaire de fichiers à deux panneaux vous +permet de voir le contenu d'un fichier iso dans un panneau et de télécharger +les fichiers via FTP dans l'autre panneau. Même si cette méthode nécessite +un travail manuel, elle ne nécessite pas les privilèges root. + +3~ Démarrer images webboot + +Tandis que certains utilisateurs vont utiliser la virtualisation pour tester +le webbooting, nous utilisons du matériel réel ici pour correspondre au +possible cas d'utilisation suivant qui seulement devrait être considéré +comme un exemple. + +Afin de démarrer une image webboot il suffit d'avoir les éléments mentionnés +ci-dessus, c'est-à-dire, #{vmlinuz}# et #{initrd.img}# sur une clé usb dans +un répertoire nommé #{live/}# et installer syslinux comme chargeur de +démarrage. Ensuite, démarrer à partir de la clé usb et taper +#{fetch=URL/CHEMIN/DU/FICHIER}# aux options de démarrage. live-boot va +télécharger le fichier squashfs et le stocker dans la ram. De cette façon, +il est possible d'utiliser le système de fichiers compressé téléchargé comme +un système live normal. Par exemple: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Cas d'utilisation:}* Vous avez un serveur web dans lequel vous avez stocké deux fichiers squashfs, un qui contient un bureau complet, comme par exemple gnome, et un d'un système standard. Si vous avez besoin d'un environnement graphique pour une machine, vous pouvez brancher votre clé usb et télécharger l'image qui contient gnome. Si vous avez besoin des outils inclus dans le deuxième type d'image, peut-être pour une autre machine, vous pouvez télécharger celle du système standard. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-binary.ssi new file mode 100644 index 0000000..a19d792 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-binary.ssi @@ -0,0 +1,67 @@ +:B~ Personnalisation de l'image binaire + +1~customizing-binary Personnalisation de l'image binaire + +2~ Chargeurs d'amorçage + +live-build utilise /{syslinux}/ et certains de ses dérivés (selon le type +d'image) comme chargeurs d'amorçage par défaut. Vous pouvez facilement les +personnaliser pour répondre à vos besoins. + +Pour utiliser un thème complet, copiez #{/usr/share/live/build/bootloaders}# +dans #{config/bootloaders}# et modifiez les fichiers là. Si vous ne voulez +pas modifier toutes les configurations du chargeur d'amorçage prises en +charge, il suffit de fournir une copie locale personnalisée d'un des +chargeurs, par exemple copiez la configuration d'*{isolinux}* dans +#{config/bootloaders/isolinux}#, selon votre cas d'utilisation. + +Lors de la modification d'un des thèmes par défaut, si vous souhaitez +utiliser une image de fond personnalisée qui sera affichée avec le menu de +démarrage, ajouter une image splash.png de 640x480 pixels. Ensuite, +supprimer le fichier splash.svg. + +Il y a beaucoup de possibilités quand il s'agit de faire des +changements. Par exemple, les dérivés de syslinux sont configurés par défaut +avec un timeout de 0 (zéro), ce qui signifie qu'ils se mettront en pause +indéfiniment à leur écran de démarrage jusqu'à ce que vous pressiez une +touche. + +Pour modifier le délai de démarrage d'une image #{iso-hybrid}#, vous pouvez +modifier un fichier *{isolinux.cfg}* en précisant le timeout dans les unités +de 1/10 secondes. Un *{isolinux.cfg}* modifié pour démarrer cinq secondes +plus tard serait semblable à ceci: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ Métadonnées ISO + +En créant une image binaire ISO9660, vous pouvez utiliser les options +suivantes pour ajouter différentes métadonnées textuelles pour votre +image. Cela peut vous aider à facilement identifier la version ou la +configuration d'une image sans la démarrer. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: Cela devrait décrire +l'application qui sera sur l'image. Le nombre maximum de caractères pour ce +champ est 128. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: Cela devrait décrire le +préparateur de l'image, généralement avec certains détails de contact. Le +défaut de cette option est la version de live-build que vous utilisez, ce +qui peut faciliter le débogage plus tard. Le nombre maximum de caractères +pour ce champ est 128. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: Ce doit décrire l'éditeur de +l'image, généralement avec certains détails de contact. Le nombre maximum de +caractères pour ce champ est 128. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: Cela devrait indiquer l'ID de volume +de l'image. Il est utilisé comme une étiquette visible par l'utilisateur sur +certaines plateformes comme Windows et Apple Mac OS. Le nombre maximum de +caractères pour ce champ est 128. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-contents.ssi new file mode 100644 index 0000000..278359b --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-contents.ssi @@ -0,0 +1,145 @@ +:B~ Personnalisation des contenus + +1~customizing-contents Personnalisation des contenus + +Ce chapitre aborde la personnalisation fine des contenus du système live +au-delà du simple choix des paquets à inclure. Les inclusions vous +permettent d'ajouter ou de remplacer des fichiers arbitraires dans votre +image du système live, les hooks vous permettent d'exécuter des commandes +arbitraires dans différentes étapes de la construction et au démarrage et la +préconfiguration (preseeding) vous permet de configurer les paquets quand +ils sont installés en fournissant des réponses aux questions debconf. + +2~includes Includes + +Bien qu'idéalement un système live comprendrait des fichiers entièrement +fournis par des paquets non modifiés, il peut être pratique de fournir ou de +modifier certains contenus par le biais de fichiers. Avec les «includes», il +est possible d'ajouter (ou remplacer) des fichiers arbitraires dans votre +image du système live. live-build prévoit deux mécanismes pour leur +utilisation: + +_* Chroot local includes: Ils vous permettent d'ajouter ou remplacer des +fichiers sur le système de fichiers chroot/Live. Veuillez consulter +{Live/chroot local includes}#live-chroot-local-includes pour plus +d'informations. + +_* Binary local includes: Ils vous permettent d'ajouter ou de remplacer des +fichiers dans l'image binaire. Veuillez consulter {Binary local +includes}#binary-local-includes pour plus d'informations. + +Veuillez consulter les {Termes}#terms pour plus d'informations sur la +distinction entre les images "Live" et "binary". + +3~live-chroot-local-includes Live/chroot local includes + +Les chroot local includes peuvent être utilisés pour ajouter ou remplacer +des fichiers dans le système de fichiers chroot/Live afin qu'ils puissent +être utilisés dans le système Live. Une utilisation typique est de peupler +l'arborescence du répertoire de l'utilisateur (#{/etc/skel}#) utilisée par +le système live pour créer le répertoire home de l'utilisateur Live. Une +autre est de fournir des fichiers de configuration qui peuvent être +simplement ajoutés ou remplacés à l'image sans traitement, voir {Live/chroot +local hooks}#live-chroot-local-hooks si le traitement est nécessaire. + +Pour inclure des fichiers, il suffit de les ajouter à votre répertoire +#{config/includes.chroot}#. Ce répertoire correspond au répertoire racine +#{/}# du système live. Par exemple, pour ajouter un fichier +#{/var/www/index.html}# dans le système live, utilisez: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Votre configuration aura alors le schéma suivant: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Les chroot local includes sont installés après l'installation de paquets de +sorte que les fichiers installés par les paquets sont remplacés. + +3~binary-local-includes Binary local includes + +Pour inclure des matériels tels que des documents ou des vidéos sur le +système de fichiers des supports, afin qu'ils soient accessibles dès +l'insertion du support sans démarrer le système live, vous pouvez utiliser +binary local includes. Cela fonctionne de façon similaire aux chroot local +includes. Par exemple, supposons que les fichiers #{~/video_demo.*}# sont +des vidéos de démonstration du système live décrits par et liés par une page +d'index HTML. Copiez simplement le matériel dans #{config/includes.binary/}# +comme suit: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +Ces fichiers apparaissent maintenant dans le répertoire racine du support +live. + +2~hooks Hooks + +Les hooks permettent l'exécution des commandes dans les étapes de la +construction chroot et binary afin de personnaliser l'image. + +3~live-chroot-local-hooks Live/chroot local hooks + +Pour exécuter des commandes à l'étape chroot, créer un script hook avec le +suffixe #{.hook.chroot}# contenant les commandes dans le répertoire +#{config/hooks/}#. Le hook s'exécutera dans le chroot après que le reste de +votre configuration chroot ait été appliqué, donc n'oubliez pas de vous +assurer que votre configuration inclut tous les paquets et les fichiers dont +votre hook a besoin pour fonctionner. Consultez les exemples de scripts +chroot hook pour diverses tâches courantes de personnalisation chroot +fournis dans #{/usr/share/doc/live-build/examples/hooks}# que vous pouvez +copier ou faire un lien symbolique pour les utiliser dans votre propre +configuration. + +3~boot-time-hooks Hooks pendant le démarrage + +Pour exécuter des commandes pendant le démarrage, vous pouvez fournir +live-config hooks comme expliqué dans la section "Personnalisation" de sa +page de manuel. Examinez les hooks de live-config fournis dans +#{/lib/live/config/}#, en notant les numéros de séquence. Fournissez ensuite +votre propre hook précédé d'un numéro de séquence appropriée, soit comme un +chroot local include dans #{config/includes.chroot/lib/live/config/}#, soit +comme un paquet personnalisé tel que discuté dans {Installation des paquets +modifiés ou de tiers}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +Pour exécuter des commandes à l'étape binaire, créez un script hook avec le +suffixe #{.hook.binary}# contenant les commandes dans le répertoire +#{config/hooks/}#. Le hook sera exécuté après toutes les autres commandes +binaires, mais avant binary_checksums, la dernière commande binaire. Les +commandes de votre hook ne s'exécutent pas dans le chroot, afin de prendre +soin de ne pas modifier les fichiers en dehors de l'arbre de construction, +ou vous pourriez endommager votre système de construction! Consultez les +exemples de scripts de binary hook pour diverses tâches courantes de +personnalisation binaires fournis dans +#{/usr/share/doc/live-build/examples/hooks}# que vous pouvez copier ou lier +symboliquement pour les utiliser dans votre propre configuration. + +2~ Préconfigurer questions de debconf + +Les fichiers dans le répertoire #{config/preseed/}# avec le suffixe #{.cfg}# +suivis de l'étape (#{.chroot}# or #{.binary}#) sont considérés comme des +fichiers de préconfiguration debconf et sont installés par live-build en +utilisant #{debconf-set-selections}#. + +Pour plus d'informations sur debconf, veuillez consulter #{debconf(7)}# dans +le paquet /{debconf}/. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-installer.ssi new file mode 100644 index 0000000..d51b2ef --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-installer.ssi @@ -0,0 +1,92 @@ +:B~ Personnalisation de l'installateur Debian + +1~customizing-installer Personnalisation du contenu pour l'installateur +Debian + +Les images des systèmes live peuvent être intégrées avec l'installateur +Debian. Il y a un certain nombre de types d'installation différents, variant +en fonction de ce qui est inclus et de la façon dont fonctionne +l'installateur. + +Veuillez noter l'utilisation prudente des lettres majuscules pour désigner +«l'Installateur Debian» dans cette section - lorsqu'il est utilisé comme +cela, nous faisons explicitement référence à l'installateur officiel pour le +système Debian. On le voit souvent abrégé en «d-i». + +2~ Types d'installateur Debian + +Les trois principaux types de programme d'installation sont: + +*{Installateur Debian «Normal»}*: C'est une image du système live avec un noyau et initrd séparés qui (lorsqu'ils sont sélectionnés à partir du chargeur d'amorçage approprié) se lancent dans une instance d'installateur Debian standard, exactement comme si vous aviez téléchargé une image de CD de Debian et l'aviez démarrée. Les images contenant un système live et un installateur indépendant sont souvent appelées «images combinées». + +Sur ces images, Debian est installé par l'extraction et l'installation de +paquets .deb à l'aide de /{debootstrap}/, à partir des supports locaux ou du +réseau, résultant en un système Debian par défaut installé sur le disque +dur. + +Tout ce processus peut être préconfiguré et personnalisé d'un certain nombre +de façons. Consultez les pages correspondantes dans le manuel de +l'Installateur Debian pour plus d'informations. Une fois que vous avez un +fichier de préconfiguration qui fonctionne, live-build peut automatiquement +l'ajouter à l'image et l'activer pour vous. + +*{Installateur Debian "Live" }*: C'est une image du système live avec un noyau et initrd séparés qui (lorsqu'ils sont sélectionnés à partir du chargeur d'amorçage approprié) se lancent dans une instance de l'installateur Debian. + +L'installation continue de manière identique à l'installation «normale» +décrite ci-dessus, mais à l'étape de l'installation des paquets, au lieu +d'utiliser /{debootstrap}/ pour aller chercher et installer des paquets, +l'image du système de fichiers live est copiée vers la cible. Ce résultat +est obtenu avec un udeb spécial appelé live-installer. + +Après cette étape, l'installateur Debian continue normalement, en installant +et configurant des éléments tels que les chargeurs d'amorçage et les +utilisateurs locaux, etc. + +*{Remarque:}* Pour prendre en charge les deux options − installateur normal et live − dans le chargeur d'amorçage du même support live, vous devez désactiver live-installer en utilisant la préconfiguration #{live-installer/enable=false}#. + +*{Installateur Debian "de bureau"}*: Indépendamment du type d'installateur Debian inclus, #{d-i}# peut être lancé à partir du bureau en cliquant sur une icône, ce qui est plus facile à utiliser dans certaines situations. Pour pouvoir en faire usage, le paquet debian-installer-launcher doit être inclus. + +Notez que, par défaut, live-build n'inclut pas les images de l'installateur +Debian dans les images, il doit être spécifiquement activé avec #{lb +config}#. De même, veuillez noter que pour que l'installateur "de bureau" +fonctionne, le noyau du système live doit correspondre au noyau que #{d-i}# +utilise pour l'architecture indiquée. Par exemple: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Personnalisation de l'installateur Debian par préconfiguration + +Comme décrit dans le manuel de Debian Installer, appendice B sur +https://www.debian.org/releases/stable/i386/apb.html, +«La préconfiguration est une façon de donner des réponses aux questions +posées pendant le processus d'installation, sans avoir à entrer manuellement +les réponses alors que l'installation est en marche. Cela permet +d'automatiser entièrement la plupart des types d'installation et elle offre +certaines fonctionnalités que ne sont pas disponibles pendant les +installations normales ». Ce type de personnalisation se fait mieux avec +live-build en plaçant la configuration dans un fichier #{preseed.cfg}# +inclus dans #{config/includes.installer/}#. Par exemple, pour préconfigurer +les paramètres régionaux pour #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Personnalisation de contenu pour l'Installateur Debian + +À des fins expérimentales ou de débogage, vous pouvez inclure des paquets +udeb #{d-i}# construits localement. Placez-les dans +#{config/packages.binary/}# pour les inclure dans l'image. Plusieurs +fichiers supplémentaires ou de remplacement et plusieurs répertoires peuvent +aussi être inclus dans l'initrd de l'installateur, d'une manière similaire à +{Live/chroot local includes}#live-chroot-local-includes en plaçant le +contenu dans #{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-overview.ssi new file mode 100644 index 0000000..4bf6b1c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-overview.ssi @@ -0,0 +1,84 @@ +:B~ Personnalisation des contenus + +1~customization-overview Vue d'ensemble de la personnalisation + +Ce chapitre donne un aperçu des diverses façons dont vous pouvez +personnaliser un système live. + +2~ Configuration pendant la construction vs. l'amorçage + +Les options de configuration d'un système live sont divisées en options au +moment de la construction, ces options sont appliquées pendant la création +et des options au moment du démarrage, qui sont appliquées pendant le +démarrage. Les options au moment du démarrage sont divisées en celles qui +surviennent au début, appliquées par le paquet live-boot, et celles qui +arrivent plus tard, appliquées par live-config. Toute option d'amorçage peut +être modifiée par l'utilisateur en l'indiquant à l'invite de +démarrage. L'image peut également être construite avec les paramètres de +démarrage par défaut et alors les utilisateurs peuvent normalement démarrer +directement le système live sans indiquer aucune option lorsque toutes les +valeurs par défaut sont appropriées. En particulier, l'argument #{lb +--bootappend-live}# se compose de toutes les options de ligne de commande du +noyau par défaut pour le système live, comme la persistance, les claviers, +ou le fuseau horaire. Voir {Personnalisation des paramètres régionaux et la +langue}#customizing-locale-and-language, par exemple. + +Les options de configuration pendant la construction sont décrites dans la +page de manuel pour #{lb config}#. Les options de configuration pendant +l'amorçage sont décrites dans les pages de manuel pour live-boot et +live-config. Bien que les paquets live-boot et live-config soient installés +dans le système live que vous construisez, il est recommandé que vous les +installiez également sur votre système de construction pour vous y référer +facilement lorsque vous travaillez sur votre configuration. Cela peut être +fait sans danger car aucun des scripts contenus ne sont exécutés à moins que +le système soit configuré comme un système live. + +2~stages-of-the-build Étapes de la construction + +Le processus de construction est divisé en étapes, avec des +personnalisations différentes appliquées dans l'ordre dans chaque étape. La +première étape à exécuter est l'étape *{bootstrap}*. C'est la phase initiale +de peuplement du répertoire chroot avec des paquets pour faire un système +Debian de base. Elle est suivie par l'étape *{chroot}*, qui complète la +construction du répertoire chroot, le peuplant de tous les paquets listés +dans la configuration, ainsi que tout autre matériel. La plupart de la +personnalisation du contenu se produit à ce stade. La dernière étape de la +préparation de l'image live est l'étape *{binary}*, qui construit une image +amorçable, en utilisant le contenu du répertoire chroot pour construire le +système de fichiers racine pour le système Live. Il comprend l'installateur +et tout autre matériel supplémentaire sur le support cible en dehors du +système de fichiers du système live. Quand l'image live est construite, s'il +est activé, le tarball des sources est construit dans l'étape *{source}*. + +À chacune de ces étapes, les commandes sont appliquées dans un ordre +particulier. Les commandes sont ordonnées de manière à assurer que les +personnalisations puissent être superposées de manière raisonnable. Par +exemple, dans l'étape *{chroot}*, les préconfigurations sont appliqués avant +que tous les paquets ne soient installés, les paquets sont installés avant +que tous les fichiers locaux inclus ne soient copiés et les hooks sont +exécutés plus tard, quand tous les matériaux sont en place. + +2~ Supplément lb config avec des fichiers + +Bien que #{lb config}# crée une arborescence de configuration dans le +répertoire #{config/}#, pour accomplir vos objectifs, vous pourriez avoir +besoin de fournir des fichiers supplémentaires dans les sous-répertoires de +#{config/}#. Selon l'endroit où les fichiers sont stockés dans la +configuration, ils peuvent être copiés dans le système de fichiers du +système live ou dans le système de fichiers de l'image binaire, ou peuvent +fournir pendant la construction des configurations du système qui seraient +lourdes à passer comme options de la ligne de commande. Vous pouvez inclure +des choses telles que des listes personnalisées de paquets, art +personnalisé, ou des scripts hook à exécuter, soit pendant la construction +soit au démarrage, ce qui augmente la flexibilité déjà considérable de +debian-live avec le code de votre choix. + +2~ Tâches de personnalisation + +Les chapitres suivants sont organisés par les types des tâches de +personnalisation que les utilisateurs effectuent généralement: +{Personnalisation de l'installation de +paquets}#customizing-package-installation, {Personnalisation des +contenus}#customizing-contents et {Personnalisation des paramètres régionaux +et la langue}#customizing-locale-and-language couvrent quelques choses que +vous pourriez vouloir faire. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-packages.ssi new file mode 100644 index 0000000..ebcfbc0 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-packages.ssi @@ -0,0 +1,695 @@ +:B~ Personnalisation de l'installation de paquets + +1~customizing-package-installation Personnalisation de l'installation de +paquets + +La personnalisation la plus fondamentale d'un système live est sans doute la +sélection des paquets à inclure dans l'image. Ce chapitre vous guide tout au +long des différentes options de construction pour personnaliser +l'installation des paquets avec live-build. Le plus large choix influençant +les paquets disponibles pour l'installation dans l'image sont la +distribution et les zones d'archive. Afin de vous assurer des vitesses de +téléchargement décentes, vous devez choisir un miroir de distribution +proche. Vous pouvez également ajouter vos propres dépôts pour les +rétroportages, paquets expérimentaux ou personnalisés, ou inclure des +paquets directement comme fichiers. Vous pouvez définir des listes de +paquets, incluant des métapaquets qui installent en même temps de nombreux +paquets liés, tels que les paquets pour ordinateurs de bureau ou une langue +particulière. Enfin, un certain nombre d'options donne un certain contrôle +sur /{apt}/, ou si vous préférez, /{aptitude}/, pendant la construction +quand les paquets sont installés. Vous pouvez trouver cela très pratique si +vous utilisez un proxy, si vous voulez désactiver l'installation des paquets +recommandés pour économiser l'espace, ou avez besoin de contrôler quelles +versions des paquets sont installées via APT pinning, pour ne nommer que +quelques possibilités. + +2~ Sources des paquets + +3~ Distribution, zones d'archive et mode + +La distribution que vous choisissez a le plus large impact sur les paquets +qui sont disponibles pour l'inclusion dans votre image live. Indiquez le nom +de code, qui est par défaut ${testing} pour la version de live-build dans +${testing}. Toute distribution actuelle dans l'archive peut être indiquée +par son nom de code ici. (Voir {Termes}#terms pour plus de détails.) +L'option #{--distribution}# influence non seulement la source des paquets +dans l'archive, mais indique également à live-build comment construire +chaque distribution prise en charge. Par exemple, pour construire sur +*{unstable}*, sid, précisez: + +code{ + + $ lb config --distribution sid + +}code + +Dans l'archive de distribution, les zones d'archive («archive areas») sont +les principales divisions de l'archive. Dans Debian, ce sont #{main}#, +#{contrib}# et #{non-free}#. Seule #{main}# contient des logiciels qui font +partie de la distribution Debian, c'est donc la valeur par défaut. Une ou +plusieurs valeurs peuvent être indiquées, par exemple: + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +La prise en charge d'experimental est disponible pour certains dérivés de +Debian grâce à l'option #{--mode}#. L'option par défaut est #{debian}# mais +seulement si vous construisez sur un système Debian ou un système +inconnu. Si #{lb config}# est appelé sur un des dérivés pris en charge, il +créera par défaut une image de ce dérivé. Si par exemple #{lb config}# est +lancé en mode #{ubuntu}#, les noms de distribution et des zones d'archives +pour ce dérivé spécifique seront gérés à la place de ceux de Debian. Le mode +modifie également le comportement de live-build en fonction des dérivés. + +*{Remarque:}* Les projets pour lesquels ces modes ont été ajoutés sont chargés d'aider les utilisateurs de ces options. Le ${project}, en retour, fournit un soutien de développement sur une base du meilleur effort seulement, en fonction des commentaires sur les projets dérivés que nous n'avons pas développés ou pris en charge nous-mêmes. + +3~ Miroirs de distribution + +L'archive Debian est répliquée sur un grand réseau de miroirs autour du +monde pour que les habitants de chaque région puissent choisir un miroir +proche ayant la meilleure vitesse de téléchargement. Chacune des options +#{--mirror-*}# régit quel miroir de distribution est utilisé dans les +différentes étapes de la construction. Rappelez-vous dans les {Étapes de la +construction}#stages-of-the-build que l'étape *{bootstrap}* a lieu quand le +chroot est initialement peuplé par /{debootstrap}/ avec un système minimal, +et l'étape *{chroot}* a lieu quand le chroot utilisé pour construire le +système de fichiers du système live est construit. Ainsi, les commutateurs +des miroirs correspondants sont utilisés pour ces étapes et plus tard, dans +l'étape *{binary}*, les valeurs #{--mirror-binary}# et +#{--mirror-binary-security}# sont utilisées, remplaçant tout miroir utilisé +dans une étape antérieure. + +3~distribution-mirrors-build-time Miroirs de distribution utilisés lors de +la construction + +Pour définir les miroirs de distribution utilisés pendant la construction +pour pointer vers un miroir local, il suffit de fixer #{--mirror-bootstrap}# +et #{--mirror-chroot-security}# comme suit. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +Le miroir chroot, indiqué avec #{--mirror-chroot}#, est par défaut la valeur +de #{--mirror-bootstrap}#. + +3~ Miroirs de distribution utilisés pendant l'exécution + +Les options #{--mirror-binary*}# régissent les miroirs de distribution +placés dans l'image binaire. Elles peuvent être utilisées pour installer des +paquets supplémentaires lors de l'exécution du système live. Les valeurs par +défaut emploient #{httpredir.debian.org}#, un service qui choisit un miroir +géographiquement proche basé, entre autres choses, sur la famille IP de +l'utilisateur et la disponibilité des miroirs. C'est un choix approprié +lorsque vous ne pouvez pas prédire quel miroir sera le meilleur pour tous +vos utilisateurs. Autrement, vous pouvez indiquer vos propres valeurs, comme +indiqué dans l'exemple ci-dessous. Une image construite avec cette +configuration ne serait appropriée que pour les utilisateurs sur un réseau +où le "#{mirror}#" est accessible. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Dépôts additionnels + +Vous pouvez ajouter d'autres dépôts, élargissant votre choix de paquets +au-delà de ceux disponibles dans votre distribution cible. Cela peut être, +par exemple, pour avoir des paquets rétroportés, personnalisés ou +expérimentaux. Pour configurer des dépôts supplémentaires, créez les +fichiers #{config/archives/your-repository.list.chroot}#, et/ou +#{config/archives/your-repository.list.binary}#. Comme avec les options +#{--mirror-*}#, ces fichiers donnent les dépôts utilisés dans l'étape +*{chroot}* lors de la construction de l'image, et dans l'étape *{binary}*, +c'est-à-dire pendant l'exécution du système live. + +Par exemple, #{config/archives/live.list.chroot}# vous permet d'installer +les paquets du dépôt des instantanés debian live pendant la construction du +système live. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +Si vous ajoutez la même ligne à #{config/archives/live.list.binary}#, le +dépôt sera ajouté au répertoire #{/etc/apt/sources.list.d/}# de votre +système live. + +Si ces fichiers existent, ils seront sélectionnés automatiquement. + +Vous devriez également mettre la clé GPG utilisée pour signer le dépôt dans +les fichiers #{config/archives/your-repository.key.{binary,chroot}}# + +Si vous avez besoin d'un APT pinning personnalisé, les préférences APT +peuvent être placées dans les fichiers +#{config/archives/your-repository.pref.{binary,chroot}}# et elles seront +automatiquement ajoutées à votre système live dans le répertoire +#{/etc/apt/preferences.d/}#. + +2~choosing-packages-to-install Choisir les paquets à installer + +Il y a un certain nombre de façons pour choisir quels paquets live-build +s'installeront dans votre image, couvrant toute une variété de besoins. Vous +pouvez tout simplement nommer les paquets individuels à installer dans une +liste de paquets. Vous pouvez également choisir des métapaquets dans ces +listes, ou les sélectionner en utilisant les champs de contrôle de fichiers +des paquets. Enfin, vous pouvez placer des paquets dans votre arbre +#{config/}# qui est bien adapté aux essais de nouveaux paquets ou +expérimentaux avant qu'ils ne soient disponibles sur un dépôt. + +3~package-lists Listes de paquets + +Les listes de paquets sont un excellent moyen d'exprimer quels paquets +doivent être installés. La syntaxe de la liste gère des sections +conditionnelles, ce qui les rend faciles à construire et à adapter pour leur +utilisation dans des configurations multiples. Les noms des paquets peuvent +également être injectés dans la liste en utilisant des assistants de shell +pendant la construction. + +*{Remarque:}* Le comportement de live-build pour indiquer un paquet qui n'existe pas est déterminé par votre choix de l'utilitaire APT. Consultez {Choisir apt ou aptitude}#choosing-apt-or-aptitude pour plus de détails. + +3~using-metapackages Utilisation des métapaquets + +La façon la plus simple de remplir votre liste de paquets consiste à +utiliser un métapaquet de tâche maintenu par votre distribution. Par +exemple: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +Cela remplace l'ancienne méthode des listes prédéfinies gérée dans +#{live-build}# 2.x. Contrairement aux listes prédéfinies, les métapaquets ne +sont pas spécifiques au projet Live Systems. Au lieu de cela, ils sont +maintenus par des groupes de travail spécialisés dans la distribution et +reflètent donc le consensus de chaque groupe sur les paquets pour mieux +servir les besoins des utilisateurs. Ils couvrent également une gamme +beaucoup plus large des cas d'utilisation que les listes prédéfinies qu'ils +remplacent. + +Tous les métapaquets de tâches sont préfixés avec #{task-}#, donc un moyen +rapide pour déterminer lesquels sont disponibles (même s'il peut y avoir une +poignée de faux positifs dont le nom correspond mais qui ne sont pas des +métapaquets) est de faire correspondre le nom du paquet avec: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +En plus, vous trouverez d'autres métapaquets à des fins diverses. Certains +sont des sous-ensembles de paquets de tâches plus larges, comme +#{gnome-core}#, tandis que d'autres sont des pièces individuelles +spécialisées d'un Debian Pure Blend, comme les métapaquets +#{education-*}#. Pour lister tous les métapaquets dans l'archive, installez +le paquet #{debtags}# et listez tous les paquets ayant l'étiquette +#{role::metapackage}# comme suit: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Listes de paquets locaux + +Que vous listiez des métapaquets, des paquets individuels ou une combinaison +des deux, toutes les listes de paquets locaux sont stockées dans +#{config/package-lists/}#. Comme plus d'une liste peut être utilisée, cela +se prête bien à une conception modulaire. Par exemple, vous pouvez décider +de consacrer une liste à un choix particulier de bureau, l'autre à une +collection de paquets connexes qui pourraient aussi bien être utilisés +au-dessus d'un bureau différent. Cela vous permet d'expérimenter avec +différentes combinaisons d'ensembles de paquets avec un minimum de tracas en +utilisant des listes communes entre les différents projets d'images live. + +Les listes de paquets qui existent dans ce répertoire ont besoin d'avoir un +suffixe #{.list}# pour être traitées, puis un suffixe d'étape supplémentaire +#{.chroot}# ou #{.binary}# pour indiquer à quelle étape la liste est +destinée. + +*{Remarque:}* Si vous n'indiquez pas le suffixe de l'étape, la liste sera utilisée pour les deux étapes. Normalement, vous voulez indiquer #{.list.chroot}# de sorte que les paquets soient seulement installés dans le système de fichiers live et ne pas avoir une copie supplémentaire des #{.deb}# placée sur le support. + +3~ Listes de paquets locaux pour l'étape binary + +Pour faire une liste pour l'étape binary, placez un fichier avec le suffixe +#{.list.binary}# dans #{config/package-lists/}#. Ces paquets ne sont pas +installés dans le système de fichiers live, mais sont inclus sur le support +live sous #{pool/}#. Vous utiliserez généralement cette liste avec une des +variantes d'installation non-live. Comme mentionné ci-dessus, si vous voulez +que cette liste soit la même que votre liste pour l'étape chroot, utilisez +simplement le suffixe #{.list}#. + +3~generated-package-lists Listes de paquets générées + +Il arrive parfois que la meilleure façon de composer une liste soit de la +générer avec un script. Toute ligne commençant par un point d'exclamation +indique une commande à exécuter dans le chroot lorsque l'image est +construite. Par exemple, on pourrait inclure la ligne #{! grep-aptavail -n +-sPackage -FPriority standard | sort}# dans une liste de paquets qui permet +de produire une liste triée des paquets disponibles avec #{Priority: +standard}#. + +En fait, la sélection des paquets avec la commande #{grep-aptavail}# (du +paquet #{dctrl-tools}#) est si utile que #{live-build}# fournit un script +#{Packages}# à titre de commodité. Ce script accepte deux arguments: +#{field}# et #{pattern}#. Ainsi, vous pouvez créer une liste avec le contenu +suivant: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Utiliser des conditions dans les listes de paquets + +Toutes les variables de configuration de live-build stockées dans +#{config/*}# (sans le préfixe #{LB_}#) peuvent être utilisées dans des +instructions conditionnelles dans les listes de paquets. Généralement, cela +correspond à toute option #{lb config}# en majuscule et avec tirets changés +en caractères de soulignement. Mais en pratique, ce ne sont que celles qui +influencent la sélection des paquets qui font sens, comme #{DISTRIBUTION}#, +#{ARCHITECTURES}# ou #{ARCHIVE_AREAS}#. + +Par exemple, pour installer #{ia32-libs}# si #{--architectures amd64}# est +indiqué: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +Vous pouvez tester pour un certain nombre de valeurs, par exemple pour +installer /{memtest86+}/ si #{--architectures i386}# ou #{--architectures +amd64}# est indiqué: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +Vous pouvez également tester avec des variables pouvant contenir plus d'une +valeur, par exemple pour installer /{vrms}/ si #{contrib}# ou #{non-free}# +est indiqué via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +L'imbrication des conditions n'est pas prise en charge. + +% FIXME: + +3~ Suppression de paquets lors de l'installation + +Il est possible de lister des paquets dans des fichiers utilisant les +extensions #{.list.chroot_live}# et #{.list.chroot_install}# à l'intérieur +du répertoire #{config/package-lists}#. Si une liste «install» et une liste +«live» existent conjointement, les paquets dans la liste +#{.list.chroot_live}# seront supprimés par un hook après l'installation (si +l'utilisateur utilise l'installeur). Les paquets dans la liste +#{.list.chroot_install}# sont présents à la fois dans le système live et +dans le système installé. Il s'agit d'un paramétrage spécial pour +l'installeur et peut se révéler utile si vous avez choisi +#{--debian-installer live}# dans votre configuration, et souhaitez supprimer +des paquets spécifiques aux systèmes live lors de l'installation. + +3~desktop-and-language-tasks Tâches de bureau et de langue + +Les tâches de bureau et de langue sont des cas particuliers qui ont besoin +d'une certaine planification et de configuration supplémentaire. Dans +l'installateur Debian, si le support a été préparé pour un environnement de +bureau particulier, la tâche correspondante sera automatiquement +installée. Ainsi, il y a tâches internes #{gnome-desktop}#, #{kde-desktop}#, +#{lxde-desktop}# et #{xfce-desktop}#, dont aucune n'est proposée dans le +menu #{tasksel}#. De même, il n'y a pas d'élément de menu pour les tâches de +langue, mais le choix de la langue de l'utilisateur lors de l'installation +influence le choix des tâches de langue correspondantes. + +Lors du développement d'une image de bureau live, l'image s'amorce +généralement directement sur un bureau de travail. Les choix de +l'environnement de bureau et la langue par défaut ont été faits pendant la +construction et non pas pendant l'exécution comme dans le cas de +l'installateur de Debian. Cela ne veut pas dire qu'une image live ne +pourrait pas être construite pour prendre en charge plusieurs environnements +de bureau ou plusieurs langues et offrir à l'utilisateur un choix, mais ce +n'est pas le comportement par défaut de live-build. + +Comme aucune disposition n'est faite automatiquement pour les tâches de la +langue, qui comprennent des éléments tels que des polices spécifiques à la +langue et des paquets de méthodes de saisie, vous devez les indiquer dans +votre configuration si vous les voulez. Par exemple, une image de bureau +GNOME contenant la prise en charge de l'allemand pourrait inclure les +métapaquets de tâches suivants: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Version et type de noyau + +Un ou plusieurs types de noyau seront inclus dans votre image par défaut, en +fonction de l'architecture. Vous pouvez choisir différents types avec +l'option #{--linux-flavours}#. Chaque type est suffixé à partir de +#{linux-image}# pour former le nom de chaque métapaquet qui dépend à son +tour d'un paquet noyau exact à inclure dans votre image. + +Ainsi, par défaut, une image pour l'architecture #{amd64}# comprendra le +métapaquet #{linux-image-amd64}#, et une image pour l'architecture #{i386}# +comprendra le métapaquet #{linux-image-586}#. + +Lorsque plus d'une version du paquet du noyau est disponible dans vos +archives configurées, vous pouvez indiquer un nom du paquet du noyau +différent avec l'option #{--linux-packages}#. Par exemple, supposons que +vous construisiez une image pour l'architecture #{amd64}# et ajoutiez +l'archive expérimentale pour faire des essais. Pour installer le noyau +#{linux-image-3.18.0-trunk-amd64}# vous pouvez configurer cette image comme +suit: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Noyaux personnalisés + +Vous pouvez créer et inclure vos propres noyaux personnalisés, à condition +qu'ils soient intégrés dans le système de gestion des paquets Debian. Le +système de live-build ne gère pas les noyaux qui ne sont pas construits sous +forme de paquets #{.deb}#. + +La façon correcte et recommandée de déployer vos propres paquets du noyau +est de suivre les instructions dans le #{kernel-handbook}#. N'oubliez pas de +modifier l'ABI et les suffixes de manière appropriée, puis d'inclure une +construction complète des paquets #{linux}# et #{linux-latest}# dans votre +dépôt. + +Si vous optez pour la construction des paquets du noyau sans les métapaquets +correspondants, vous devez indiquer une chaîne #{--linux-packages}# +appropriée tel que discuté dans {Version et type de +noyau}#kernel-flavour-and-version. Comme nous l'expliquons dans +{Installation de paquets modifiés ou +tiers}#installing-modified-or-third-party-packages, il est préférable que +vous incluiez vos paquets de noyau personnalisés à votre propre dépôt, bien +que les alternatives discutées dans cette section fonctionnent bien +également. + +Donner des conseils sur la façon de personnaliser votre noyau sort du cadre +de ce document. Toutefois, vous devez au moins vous assurer que votre +configuration répond à ces exigences minimales: + +_* Utilisez un ramdisk initial. + +_* Incluez un module d'union de systèmes de fichiers (par exemple #{aufs}#). + +_* Incluez tous les autres modules du système de fichiers requis pour votre +configuration (habituellement #{squashfs}#). + +2~installing-modified-or-third-party-packages Installation de paquets +modifiés ou tiers + +Bien que ce soit contre la philosophie d'un système live, il peut parfois +être nécessaire de construire un système live avec des versions modifiées +des paquets du dépôt Debian. Cela peut être pour modifier ou prendre en +charge des fonctionnalités supplémentaires, des langues et la marque, ou +même pour supprimer des éléments indésirable dans les paquets existants.De +même, les paquets «tiers» peuvent être utilisés pour ajouter des +fonctionnalités sur mesure et/ou propriétaires. + +Cette section ne couvre pas les conseils concernant la construction ou la +maintenance des paquets modifiés. La méthode de Joachim Breitner 'How to +fork privately' +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +peut, cependant, vous intéresser. La création de paquets sur mesure est +traitée dans le guide du nouveau mainteneur Debian à +https://www.debian.org/doc/maint-guide/ et ailleurs + +Il y a deux façons d'installer des paquets personnalisés modifiés: + +_* #{packages.chroot}# + +_* Utiliser un dépôt APT personnalisé + +Utiliser #{packages.chroot}# est plus simple à réaliser et utile pour les +personnalisations ponctuelles mais a un certain nombre d'inconvénients, +alors qu'utiliser un dépôt personnalisé APT est plus fastidieux à mettre en +place. + +3~ Utiliser #{packages.chroot}# pour installer des paquets personnalisés + +Pour installer un paquet personnalisé, il suffit de le copier dans le +répertoire #{config/packages.chroot/}#. Les paquets qui sont dans ce +répertoire seront automatiquement installés dans le système live pendant la +construction du système - vous n'avez pas besoin de les indiquer ailleurs. + +Les paquets *{doivent}* être nommés de la manière prescrite. Une façon +simple de le faire consiste à utiliser #{dpkg-name}#. + +L'utilisation de #{packages.chroot}# pour l'installation de paquets +personnalisés a des inconvénients: + +_* Il n'est pas possible d'utiliser APT de façon sécurisée. + +_* Vous devez installer tous les paquets appropriés dans le répertoire +#{config/packages.chroot/}#. + +_* Il ne se prête pas au stockage de configurations des systèmes live dans +le contrôle de révision. + +3~ Utiliser un dépôt APT pour installer des paquets personnalisés. + +Contrairement à l'utilisation de #{packages.chroot}#, lorsque vous utilisez +un dépôt personnalisé APT, vous devez vous assurer que vous indiquez les +paquets ailleurs. Voir {Choisir les paquets à +installer}#choosing-packages-to-install pour plus de détails. + +S'il peut sembler inutile de créer un dépôt APT pour installer des paquets +personnalisés, l'infrastructure peut être facilement réutilisée à une date +ultérieure pour offrir les mises à jour des paquets modifiés. + +3~ Les paquets personnalisés et APT + +live-build utilise apt pour installer tous les paquets dans le système live, +il héritera donc des comportements de ce logiciel. Un exemple pertinent est +que (en supposant une configuration par défaut), s'il y a un paquet +disponible dans deux dépôts différents avec des numéros de version +différents, APT choisira d'installer le paquet ayant le numéro de version le +plus grand. + +Pour cette raison, vous pouvez incrémenter le numéro de version dans les +fichiers #{debian/changelog}# de vos paquets personnalisés pour vous assurer +que votre version modifiée sera installée au lieu d'une autre provenant des +dépôts officiels Debian. Cela peut aussi être afait en modifiant les +préférences d'APT pinning dans le système live − voir {APT +pinning}#apt-pinning pour plus d'informations. + +2~ Configuration d'APT pendant la construction + +Vous pouvez configurer APT par un certain nombre d'options appliquées +uniquement pendant la construction. (La configuration d'APT utilisée dans le +système live en fonctionnement peut être configurée de façon normale pour un +système live, c'est-à-dire en incluant les configurations appropriées dans +#{config/includes.chroot/}#.) Pour une liste complète, regardez les options +commençant par #{apt}# dans la page de manuel de #{lb_config}#. + +3~choosing-apt-or-aptitude Choisir apt ou aptitude + +Vous pouvez choisir d'utiliser soit /{apt}/, soit /{aptitude}/. Le choix du +logiciel utilisé dépend de l'argument #{--apt}# de #{lb config}#. Choisissez +la méthode ayant le comportement que vous préférez pour l'installation de +paquets, la différence notable étant la manière dont les paquets manquants +sont traités. + +_* #{apt}#: Avec cette méthode, si un paquet manquant est indiqué, +l'installation va échouer. C'est le réglage par défaut. + +_* #{aptitude}#: Avec cette méthode, si un paquet manquant est indiqué, +l'installation va réussir. + +3~ Utilisation d'un proxy avec APT + +Une configuration communément requise par APT est de gérer la construction +d'une image derrière un proxy. Vous pouvez indiquer votre proxy APT avec les +options #{--apt-ftp-proxy}# ou #{--apt-http-proxy}# si nécessaire, par +exemple + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Régler APT pour économiser de l'espace + +Vous pouvez avoir besoin d'économiser de l'espace sur le support d'image, +auquel cas l'une ou l'autre ou les deux options suivantes peuvent être +d'intérêt. + +Si vous ne voulez pas inclure les index d'APT dans l'image, vous pouvez les +omettre avec: + +code{ + + $ lb config --apt-indices false + +}code + +Cela n'influencera pas les entrées dans #{/etc/apt/sources.list}#, mais +seulement le fait que #{/var/lib/apt}# contienne les fichiers index ou +non. La contrepartie est qu'APT a besoin de ces index afin d'opérer dans le +système live. Par conséquent, avant de procéder à #{apt-cache search}# ou +#{apt-get install}# par exemple, l'utilisateur doit faire #{apt-get update}# +pour créer ces index. + +Si vous trouvez que l'installation des paquets recommandés fait trop gonfler +votre image, à condition d'être prêt à faire face aux conséquences décrites +ci-dessous, vous pouvez désactiver l'option par défaut d'APT avec: + +code{ + + $ lb config --apt-recommends false + +}code + +La conséquence la plus importante de la désactivation des recommandations +est que #{live-boot}# et #{live-config}# recommandent certains paquets qui +fournissent des fonctionnalités importantes utilisées par la plupart de +configurations live, telles que #{user-setup}# qui est recommandé par +#{live-config}# qui est utilisé pour créer l'utilisateur live. Sauf +exception, vous aurez besoin de rajouter au moins certaines de ces +recommandationss à vos listes de paquets ou votre image ne fonctionnera pas +comme prévu, si elle fonctionne. Regardez les paquets recommandés pour +chacun des paquets #{live-*}# inclus dans votre construction et si vous +n'êtes pas sûr de pouvoir les omettre, ajoutez-les à nouveau dans vos listes +de paquets. + +La conséquence la plus générale est que si vous n'installez pas les paquets +recommandés par un paquet, c’est-à-dire les «paquets qu'on trouverait avec +celui-ci dans toute installation standard» (Debian Policy Manual, section +7.2), certains paquets dont vous avez vraiment besoin peuvent être omis. Par +conséquent, nous vous suggérons d'examiner la différence que la +désactivation des recommandations induit sur votre liste de paquets (voir le +fichier #{binary.packages}# généré par #{lb build}#) et incluez dans votre +liste tous les paquets manquants que vous souhaitez toujours +installer. Alternativement, si seulement un petit nombre de paquets que vous +ne souhaitez pas est exclus, laissez les recommandations activées et +définissez une priorité APT pin négative sur les paquets sélectionnés pour +éviter les installer, comme expliqué dans {APT pinning}#apt-pinning. + +3~ Passer des options à apt ou aptitude + +S'il n'y a pas d'option #{lb config}# pour modifier le comportement d'APT de +la façon dont vous avez besoin, utilisez #{--apt-options}# ou +#{--aptitude-options}# pour passer des options par le biais de l'outil APT +configuré. Consultez les pages de manuel #{apt}# et #{aptitude}# pour les +détails. Notez que les deux options ont des valeurs par défaut que vous +aurez besoin de conserver en plus des remplacements que vous pouvez +fournir. Ainsi, par exemple, supposons que vous ayez inclus quelque chose de +#{snapshot.debian.org}# à des fins de test et que vous vouliez indiquer +#{Acquire::Check-Valid-Until=false}# pour satisfaire APT avec le fichier +#{Release}# obsolète. Vous le feriez comme dans l'exemple suivant, avec +l'ajout de la nouvelle option après la valeur par défaut #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Veuillez lire attentivement les pages de manuel pour bien comprendre ces +options et quand les utiliser. Ce n'est qu'un exemple et ne doit pas être +interprété comme un conseil pour configurer votre image de cette façon. Par +exemple, cette option ne serait pas appropriée pour une version finale d'une +image live. + +Pour les configurations plus compliquées concernant des options +#{apt.conf}#, vous pourriez vouloir créer un fichier +#{config/apt/apt.conf}#. Consultez aussi les autres options #{apt-*}# pour +obtenir quelques raccourcis pratiques pour les options fréquemment +utilisées. + +3~apt-pinning APT pinning + +Pour plus de contexte, veuillez d'abord lire la page de manuel +#{apt_preferences(5)}#. APT pinning peut être configuré soit pendant la +construction, soit pendant l'exécution. Dans le premier cas, créez +#{config/archives/*.pref}#, #{config/archives/*.pref.chroot}#, et +#{config/apt/preferences}#. Dans le second cas, créez +#{config/includes.chroot/etc/apt/preferences}#. + +Imaginons que vous voulez construire un système live ${testing} mais qu'il +faut installer tous les paquets live qui finissent dans l'image binaire de +sid pendant la construction. Vous devez ajouter sid à votre fichier APT +sources et fixer tous les paquets live avec une priorité supérieure mais +tous les autres paquets avec une priorité inférieure à la priorité par +défaut de sorte que seuls les paquets que vous voulez soient installés à +partir de sid pendant la construction et que tous les autres viennent de la +distribution du système cible, ${testing}. Ce qui suit devrait accomplir +cela: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Une priorité pin négative évitera installer un paquet, comme dans le cas où +vous ne voudriez pas un paquet qui est recommandé par un autre +paquet. Supposons que vous construisiez une image LXDE en utilisant +#{task-lxde-desktop}# dans #{config/package-lists/desktop.list.chroot}# mais +que vous ne vouliez pas que l'utilisateur soit invité à stocker les mots de +passe wifi dans le trousseau de clés. Cette liste comprend /{lxde-core}/, +qui recommande /{gksu}/, qui à son tour recommande /{gnome-keyring}/. Donc, +vous voulez omettre le paquet recommandé /{gnome-keyring}/. Cela peut être +fait en ajoutant ce qui suit à #{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-runtime.ssi new file mode 100644 index 0000000..8c0b50f --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_customization-runtime.ssi @@ -0,0 +1,473 @@ +:B~ Personnalisation des comportements pendant l'exécution + +1~customizing-run-time-behaviours Personnalisation des comportements pendant +l'exécution + +Toute la configuration qui est faite pendant l'exécution est faite par +live-config. Voici quelques options parmi les plus courantes de live-config +qui peuvent intéresser les utilisateurs. Une liste complète de toutes les +possibilités peut être trouvée dans la page de manuel de live-config. + +2~ Personnalisation de l'utilisateur live + +Une considération importante est que l'utilisateur live est créé par +live-boot au démarrage, non pas par live-config pendant la +construction. Cela influence non seulement l'emplacement où les documents +relatifs à l'utilisateur live sont introduits dans la construction, tel que +discuté dans {Live/chroot local includes}#live-chroot-local-includes, mais +aussi tous les groupes et autorisations associés à l'utilisateur live. + +Vous pouvez indiquer d'autres groupes pour l'utilisateur live en utilisant +une des possibilités pour configurer live-config. Par exemple, pour ajouter +l'utilisateur live au groupe #{fuse}#, vous pouvez ajouter le fichier +suivant dans #{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +ou utiliser +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +comme paramètre d'amorçage. + +Il est également possible de changer le nom de l'utilisateur par défaut +«user» et du mot de passe par défaut «live». Si vous voulez faire cela, vous +pouvez le faire facilement comme suit: + +Pour modifier le nom de l'utilisateur par défaut, vous pouvez simplement +l'indiquer dans votre configuration: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +Une façon possible de changer le mot de passe par défaut est d'utiliser un +hook comme décrit dans {Hooks pendant le démarrage}#boot-time-hooks. Pour ce +faire vous pouvez utiliser le hook "passwd" de +#{/usr/share/doc/live-config/examples/hooks}#, ajouter un préfixe correct +(par exemple 2000-passwd) et l'ajouter à +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Personnalisation des paramètres régionaux +et de la langue + +Au démarrage du système live, la langue est impliquée dans deux étapes: + +_* la génération des paramètres régionaux + +_* le réglage de la disposition du clavier + +Les paramètres régionaux par défaut pendant la construction d'un système +Live sont #{locales=en_US.UTF-8}#. Pour définir les paramètres régionaux qui +doivent être générés, utilisez le paramètre #{locales}# dans l'option +#{--bootappend-live}# de #{lb config}#, par exemple + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Plusieurs paramètres régionaux peuvent être indiqués dans une liste séparée +par des virgules. + +Ce paramètre, ainsi que les paramètres de configuration du clavier indiqués +ci-dessous, peut également être utilisé sur la ligne de commande du +noyau. On peut indiquer des paramètres régionaux avec #{language_country}# +(dans ce cas, le codage par défaut est utilisé) ou l'expression complète +#{language_country.encoding}#. Une liste des paramètres régionaux et le +codage pour chacun peuvent être trouvés dans #{/usr/share/i18n/SUPPORTED}#. + +La configuration du clavier pour la console et pour X est faite par +#{live-config}# en utilisant le paquet #{console-setup}#. Pour les +configurer, utilisez les paramètres de démarrage #{keyboard-layouts}#, +#{keyboard-variants}#, #{keyboard-options}# et #{keyboard-model}# avec +l'option #{--bootappend-live}#. On peut trouver les options valides dans +#{/usr/share/X11/xkb/rules/base.lst}#. Pour trouver les dispositions et les +variantes correspondantes à une langue, essayez de rechercher le nom anglais +de la nation où la langue est parlée, par exemple: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Chaque variante présente une description de la disposition appliquée. + +Souvent, seule la disposition doit être configurée. Par exemple, pour +obtenir les fichiers des paramètres régionaux de l'allemand et la +disposition du clavier suisse allemand dans X, utilisez: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +Toutefois, pour les cas d'utilisation très spécifiques, on peut inclure +d'autres paramètres. Par exemple, pour mettre en place un système français +avec une disposition French-Dvorak (Bépo) avec un clavier USB TypeMatrix +EZ-Reach 2030, utilisez: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Plusieurs valeurs peuvent être indiquées dans des listes séparées par des +virgules pour chacune des options #{keyboard-*}#, à l'exception de +#{keyboard-model}# qui accepte une seule valeur. Veuillez consulter la page +de manuel #{keyboard(5)}# pour plus de détails et des exemples des variables +#{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# et #{XKBOPTIONS}#. Si plusieurs +valeurs #{keyboard-variants}# sont données, elles seront jumelées une à une +avec les valeurs #{keyboard-layouts}# (voir #{setxkbmap(1)}# option +#{-variant}#). On peut utiliser des valeurs vides; par exemple pour régler +deux dispositions, une par défaut US QWERTY et l'autre US Dvorak, utilisez: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistance + +Le paradigme d'un Live CD est d'être un système pré-installé qui amorce sur +un support en lecture seule, comme un cdrom, où les données et les +modifications ne survivent pas aux redémarrages du matériel hôte qui +l'exécute. + +Un système live est une généralisation de ce paradigme et gère ainsi +d'autres supports en plus de CDs. Malgré tout, dans son comportement par +défaut, il doit être considéré en lecture seule et toutes les évolutions +pendant l'exécution du système sont perdues à l'arrêt. + +La «persistance» est un nom commun pour les différents types de solutions +pour sauver, après un redémarrage, certaines ou toutes les données, de cette +évolution pendant l'exécution du système. Pour comprendre comment cela +fonctionne, il peut être utile de savoir que même si le système est démarré +et exécuté à partir d'un support en lecture seule, les modifications des +fichiers et répertoires sont écrites sur des supports inscriptibles, +typiquement un disque ram (tmpfs) et les données des disques RAM ne +survivent pas à un redémarrage. + +Les données stockées sur ce disque virtuel doivent être enregistrées sur un +support inscriptible persistant comme un support de stockage local, un +partage réseau ou même une séance d'un CD/DVD multisession +(ré)inscriptible. Tous ces supports sont pris en charge dans les systèmes +live de différentes manières, et tous, à part le dernier, nécessitent un +paramètre d'amorçage spécial à préciser au moment du démarrage: +#{persistence}#. + +Si le paramètre de démarrage #{persistence}# est réglé (et #{nopersistence}# +n'est pas utilisé), les supports de stockage locaux (par exemple les disques +durs, clés USB) seront examinés pour trouver des volumes persistants pendant +le démarrage. Il est possible de limiter les types de volumes persistants à +utiliser en indiquant certains paramètres de démarrage décrits dans la page +de manuel live-boot(7). Un volume persistant est un des éléments suivants: + +_* une partition, identifiée par son nom GPT. + +_* un système de fichiers, identifié par son étiquette de système de +fichiers. + +_* un fichier image situé sur la racine d'un système de fichiers en lecture +(même une partition NTFS d'un système d'exploitation étranger), identifié +par son nom de fichier. + +L'étiquette du volume pour les overlays doit être #{persistence}# mais elle +sera ignorée à moins de contenir dans sa racine un fichier nommé +#{persistence.conf}# qui est utilisé pour personnaliser entièrement la +persistance du volume, c'est-à-dire indiquer les répertoires que vous voulez +sauvegarder dans votre volume de persistance après un redémarrage. Voir {Le +fichier persistence.conf}#persistence-conf pour plus de détails. + +Voici quelques exemples montrant comment préparer un volume à utiliser pour +la persistance. Cela peut être, par exemple, une partition ext4 sur un +disque dur ou sur une clé usb créée avec: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +Voir aussi {Utilisation de l'espace disponible sur une clé +USB}#using-usb-extra-space. + +Si vous avez déjà une partition sur votre périphérique, vous pouvez +simplement modifier l'étiquette avec l'un des exemples suivants: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Voici un exemple montrant comment créer un fichier image avec un système de +fichiers ext4 pour être utilisé pour la persistance: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Une fois que le fichier image est créé, à titre d'exemple, pour rendre +#{/usr}# persistant mais seulement enregistrer les modifications que vous +apportez à ce répertoire et non pas tout le contenu de #{/usr}#, vous pouvez +utiliser l'option «union». Si le fichier image se trouve dans votre +répertoire personnel, copiez-le à la racine du système de fichiers de votre +disque dur et montez-le dans #{/mnt}# comme suit: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Ensuite, créez le fichier #{persistence.conf}# ajoutant du contenu et +démontez le fichier image. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Maintenant, redémarrez dans votre support live avec le paramètre de +démarrage "persistence". + +3~persistence-conf Le fichier persistence.conf + +Un volume ayant l'étiquette #{persistence}# doit être configuré avec un +fichier #{persistence.conf}# pour créer des répertoires persistants +arbitraires. Ce fichier, situé sur le système de fichiers racine du volume, +contrôle quels répertoires il rend persistants, et de quelle manière. + +La façon de configurer les montages overlays est décrite en détail dans la +page de manuel persistence.conf(5), mais un simple exemple devrait suffire +pour la plupart des utilisations. Imaginons que nous voulions rendre notre +répertoire personnel et APT cache persistants dans un système de fichiers +ext4 sur la partition /dev/sdb1: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Puis nous redémarrons. Lors du premier démarrage, les contenus du #{/home}# +et #{/var/cache/apt}# seront copiés dans le volume persistant. À partir de +ce moment, tous les changements dans ces répertoires seront stockés dans le +volume persistant. Veuiller remarquer que les chemins répertoriés dans le +fichier #{persistence.conf}# ne peuvent pas contenir d'espaces ou d'éléments +spéciaux #{.}# et #{..}#. En outre, ni #{/lib}#, #{/lib/live}# (ou un de +leurs sous-répertoires), ni #{/}# ne peuvent être rendus persistants en +utilisant des montages personnalisés. Comme solution à cette limitation, +vous pouvez ajouter #{/ union}# à votre fichier #{persistence.conf}# pour +obtenir une persistance complète. + +3~ Utilisation de plusieurs dispositifs de persistance + +Il existe différentes méthodes d'utilisation de multiples dispositifs de +persistance pour les différents cas d'utilisation. Par exemple, utiliser +plusieurs dispositifs à la fois ou en sélectionner un seul, entre plusieurs, +à des fins très spécifiques. + +Plusieurs volumes overlays différents (avec leurs propres fichiers +#{persistence.conf}#) peuvent être utilisés au même temps, mais si plusieurs +volumes rendent le même répertoire persistant, un seul d'entre eux sera +utilisé. Si les deux sont «imbriqués» (un est un sous-répertoire de l'autre) +le premier sera monté avant le second de sorte qu'aucun ne sera caché par +l'autre. Monter des éléments personnalisés imbriqués est problématique s'ils +sont énumérés dans le même fichier #{persistence.conf}#. Voir la page de +manuel persistence.conf(5) pour savoir comment gérer ce cas si vous en avez +vraiment besoin (remarque: ce n'est généralement pas le cas). + +Un cas d'utilisation possible: Si vous souhaitez stocker les données de +l'utilisateur, c'est-à-dire #{/home}# et les données du superutilisateur, +c'est-à-dire #{/root}# dans des partitions différentes, créer deux +partitions avec l'étiquette #{persistence}# et ajouter un fichier +#{persistence.conf}# dans chacun comme ça #{# echo "/home" > +persistence.conf}# pour la première partition qui permettra de sauver les +fichiers de l'utilisateur et #{# echo "/root" > persistence.conf}# pour la +seconde partition qui permettra de stocker les fichiers du +superutilisateur. Enfin, utiliser le paramètre d'amorçage #{persistence}#. + +Si un utilisateur a besoin de stockages persistants multiples du même type +pour différents endroits ou essais, tel que #{private}# et #{work}#, le +paramètre de démarrage #{persistence-label}# utilisé en conjonction avec le +paramètre de démarrage #{persistence}# permettra de multiples mais uniques +supports persistants. Dans le cas où un utilisateur voudrait utiliser une +partition persistante étiquetée #{private}#, pour des données personelles +comme les marque-pages du navigateur ou d'autres types, il utiliserait les +paramètres de démarrage: #{persistence}# #{persistence-label=private}#. Et +pour stocker des données liées au travail, comme des documents, des projets +de recherche ou d'autres types, il utiliserait les paramètres de démarrage: +#{persistence}# #{persistence-label=work}#. + +Il est important de se rappeler que chacun de ces volumes, #{private}# et +#{work}#, a également besoin d'un fichier #{persistence.conf}# dans sa +racine. La page de manuel live-boot contient plus d'informations sur la +façon d'utiliser ces étiquettes avec des noms ancients. + +3~ Utilisation de la persistance avec chiffrement + +Utiliser la persistance signifie que certaines données sensibles peuvent +être exposées au risque. Surtout si les données persistantes sont stockées +sur un dispositif portable tel qu'une clé USB ou un disque dur +externe. C'est quand le chiffrement est plus pratique. Même si la procédure +complète peut paraître compliquée en raison du nombre d'étapes à suivre, il +est vraiment facile de manipuler des partitions chiffrées avec +live-boot. Pour utiliser *{luks}*, qui est le type de chiffrement pris en +charge, vous devez installer /{cryptsetup}/ tant sur la machine avec +laquelle vous créez la partition chiffrée et aussi dans le système live avec +lequel vous allez utiliser la partition persistante chiffrée. + +Pour installer /{cryptsetup}/ sur votre machine: + +code{ + + # apt-get install cryptsetup + +}code + +Pour installer /{cryptsetup}/ dans votre système live, ajouter à vos listes +de paquets: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Une fois que vous avez votre système live avec /{cryptsetup}/, vous avez +essentiellement besoin de créer une nouvelle partition, la chiffrer et +démarrer avec les paramètres #{persistence}# et +#{persistence-encryption=luks}#. Nous aurions pu déjà anticipée cette étape +et ajoutée ces paramètres de démarrage selon la procédure habituelle: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Allons dans les détails pour tous ceux qui ne connaissent pas bien le +chiffrement. Dans l'exemple suivant, nous allons utiliser une partition sur +une clé usb qui correspond au dispositif #{/dev/sdc2}#. S'il vous plaît être +averti que vous devez déterminer quelle partition est celui que vous allez +utiliser dans votre cas particulier. + +La première étape est de brancher votre clé usb et de déterminer quel +dispositif il est. La méthode recommandée pour lister les dispositifs dans +live-manual est utiliser #{ls -l /dev/disk/by-id}#. Après cela, créer une +nouvelle partition et la chiffrer avec un mot de passe comme suit: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Ensuite, ouvrir la partition luks dans le mappeur de dispositifs +virtuel. Utilisez n'importe quel nom que vous aimez. Nous utilisons *{live}* +ici à titre d'exemple: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +La prochaine étape est de remplir le dispositif avec des zéros avant de +créer le système de fichiers: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Maintenant, nous sommes prêts à créer le système de fichiers. Notez que nous +ajoutons l'étiquette #{persistence}# de sorte que le dispositif est monté en +tant que magasin de persistance au moment du démarrage. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +Pour continuer avec notre configuration, nous avons besoin de monter le +dispositif, par exemple dans #{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +Et créer le fichier #{persistence.conf}# à la racine de la partition. Ceci +est, comme expliqué précédemment, strictement nécessaire. Voir {Le fichier +persistence.conf}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Puis, démontez le point de montage: + +code{ + + # umount /mnt + +}code + +Et éventuellement, bien qu'il pourrait être un bon moyen de sécuriser les +données que nous venons d'ajouter à la partition, nous pouvons fermer le +dispositif: + +code{ + + # cryptsetup luksClose live + +}code + +Résumons la procédure. Jusqu'ici nous avons créé un système capable +d'utiliser le chiffrement, qui peut être copié sur une clé usb comme +expliqué dans {Copie d'une image ISO hybride sur une clé +USB}#copying-iso-hybrid-to-usb. Nous avons également créé une partition +chiffrée, qui peut être située dans la même clé USB pour le porter autour et +nous avons configuré la partition chiffrée pour être utilisée comme magasin +de persistance. Alors maintenant, nous avons seulement besoin de démarrer le +système live. Au moment du démarrage, live-boot nous demandera le mot de +passe pour monter la partition chiffrée à être utilisé pour la persistance. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_installation.ssi new file mode 100644 index 0000000..0656468 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_installation.ssi @@ -0,0 +1,182 @@ +:B~ Installation + +1~installation Installation + +2~requirements Exigences + +Les exigences pour la création des images des systèmes live sont très +faibles: + +_* Accès super-utilisateur (root) + +_* Une version mise à jour de live-build + +_* Un shell POSIX, comme /{bash}/ ou /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6.x ou supérieur. + +Notez que l'utilisation de Debian ou d'une distribution dérivée de Debian +n'est pas nécessaire - live-build fonctionne sur presque toutes les +distributions remplissant les exigences ci-dessus. + +2~installing-live-build Installation de live-build + +Vous pouvez installer live-build d'un certain nombre de façons différentes: + +_* À partir du dépôt Debian + +_* À partir du code source + +_* À partir des instantanés + +Si vous utilisez Debian, la méthode recommandée consiste à installer +live-build à partir du dépôt Debian. + +3~ À partir du dépôt Debian + +Il suffit d'installer live-build comme n'importe quel autre paquet: + +code{ + + # apt-get install live-build + +}code + +3~ À partir du code source + +live-build est développé en utilisant le système de contrôle de version +Git. Dans les systèmes basés sur Debian, il est fourni par le paquet +/{git}/. Pour examiner le dernier code, exécutez: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +Vous pouvez compiler et installer votre propre paquet Debian en exécutant: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Maintenant, installez les fichiers récemment construits qui vous +intéressent, par exemple + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +Vous pouvez également installer live-build directement sur votre système en +exécutant: + +code{ + + # make install + +}code + +et le désinstaller avec: + +code{ + + # make uninstall + +}code + +3~ À partir des instantanés + +Si vous ne souhaitez pas créer ou installer live-build à partir des sources, +vous pouvez utiliser des instantanés. Ils sont construits automatiquement à +partir de la dernière version du dépôt Git et sont disponibles sur +http://live-systems.org/debian/. + +2~ Installation de live-boot et live-config + +*{Remarque:}* Vous n'avez pas besoin d'installer live-boot ou live-config sur votre système afin de créer des systèmes live. Cependant, cela ne fera aucun mal et est utile à des fins de référence. Si vous voulez seulement la documentation, vous pouvez maintenant installer les paquets /{live-boot-doc}/ et /{live-config-doc}/ séparément. + +3~ À partir du dépôt Debian + +live-boot et live-config sont tous les deux disponibles dans le dépôt Debian +comme expliqué dans {Installation de live-build}#installing-live-build. + +3~ À partir du code source + +Pour utiliser les dernières sources du git, vous pouvez suivre la procédure +ci-dessous. Veuillez vous assurer que vous êtes familiarisé avec les termes +mentionnés dans {Termes}#terms. + +_* Examiner les sources de live-boot et live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consultez les pages de manuel de live-boot et live-config pour plus de +détails sur la personnalisation si la raison pour laquelle vous créez vos +paquets à partir des sources. + +_* Créer les fichiers .deb de live-boot et live-config + +Vous devez créer sur votre distribution cible ou dans un chroot contenant +votre plateforme cible: cela signifie que si votre cible est ${testing} +alors vous devez créer sur ${testing}. + +Utilisez un système de construction automatique personnel tel que +/{pbuilder}/ ou /{sbuild}/ si vous avez besoin de créer live-boot pour une +distribution cible qui diffère de votre système de construction. Par +exemple, pour les images live de ${testing}, créez live-boot dans un chroot +${testing}. Si votre distribution cible correspond à votre distribution vous +pouvez créer directement sur le système de construction en utilisant +#{dpkg-buildpackage}# (fourni par le paquet /{dpkg-dev}/): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Utiliser les fichiers .deb générés nécessaires. + +Comme live-boot et live-config sont installés par le système de construction +live-build, l'installation de ces paquets dans le système hôte ne suffit +pas: vous devez traiter les fichiers .deb générés comme d'autres paquets +personnalisés. Comme votre objectif pour la construction à partir du code +source est de tester nouvelles choses à court terme avant leur publication +officielle, suivez {Installation de paquets modifiés ou de +tiers}#installing-modified-or-third-party-packages pour inclure +temporairement les fichiers pertinents dans votre configuration. En +particulier, remarquez que les deux paquets sont divisés en une partie +générique, une partie de documentation et un ou plusieurs back-ends. Incluez +la partie générique, un seul back-end et éventuellement la documentation. En +supposant que vous construisiez une image live dans le répertoire courant et +ayez généré tous les fichiers .deb pour une version unique des deux paquets +dans le répertoire ci-dessus, ces commandes bash copieraient tous les +paquets appropriés, y compris les back-ends par défaut: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ À partir des instantanés + +Vous pouvez laisser live-build utiliser automatiquement les derniers +instantanés de live-boot et live-config en configurant le dépôt tiers +live-systems.org dans votre répertoire de configuration de live-build. diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_managing_a_configuration.ssi new file mode 100644 index 0000000..cb76e96 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_managing_a_configuration.ssi @@ -0,0 +1,142 @@ +:B~ Gestion d'une configuration + +1~managing-a-configuration Gestion d'une configuration + +Ce chapitre explique comment gérer une configuration d'un système live à +partir d'une création initiale, à travers des révisions successives et des +versions successives du logiciel live-build et de l'image live elle-même. + +2~ Gérer les modifications de la configuration + +Les configurations live sont rarement parfaites du premier coup. Il peut +être bon de passer des options #{lb config}# à partir de la ligne de +commande pour effectuer une construction unique, mais il est plus courant de +réviser ces options et de construire à nouveau jusqu'à ce que vous soyez +satisfait. Afin de prendre en charge ces changements, vous aurez besoin des +scripts automatiques qui assurent le maintien de votre configuration dans un +état cohérent. + +3~ Pourquoi utiliser des scripts auto? Que font-ils? + +La commande #{lb config}# enregistre les options que vous lui passez avec +les fichiers dans #{config/*}# avec beaucoup d'autres options aux valeurs +par défaut. Si vous exécutez #{lb config}# à nouveau, il ne réinitialisera +pas l'option qui a été mise par défaut en fonction de vos options +initiales. Ainsi, par exemple, si vous exécutez #{lb config}# à nouveau avec +une nouvelle valeur pour #{--binary-images}#, toutes les options qui ont été +mises à leur valeur par défaut pour l'ancienne type d'image ne peuvent plus +fonctionner avec la nouvelle option. Ces fichiers ne sont pas destinés à +être lus ou modifiés. Ils enregistrent des valeurs pour plus d'une centaine +d'options, donc personne (y-compris vous) ne pourra voir dans ces options +lesquelles vous avez réellement indiquées. Finalement, si vous lancez #{lb +config}#, puis mettez live-build à niveau et que celui-ci renomme une +option, #{config/*}# contiendra toujours des variables nommées en fonction +de l'ancienne option et qui ne seront plus valides. + +Pour toutes ces raisons, les scripts #{auto/*}# vous rendront la vie plus +facile. Ils sont de simples emballages pour les commandes #{lb config}#, +#{lb build}# et #{lb clean}# qui sont conçus pour vous aider à gérer votre +configuration. Le script #{auto/config}# enregistre votre commande #{lb +config}# avec toutes les options désirées, le script #{auto/clean}# supprime +les fichiers contenant les valeurs des variables de configuration et le +script #{auto/build}# crée un #{build.log}# de chaque construction. Et +chaque fois que vous lancez la commande #{lb}# correspondante, ces fichiers +sont exécutés automatiquement. En utilisant ces scripts, votre configuration +est plus facile à lire et a une cohérence interne d'une révision à +l'autre. En outre, il sera plus facile pour vous d'identifier et corriger +les options qui doivent changer lorsque vous mettez à niveau live-build +après avoir lu la documentation mise à jour. + +3~ Utiliser les scripts auto d'exemple + +Pour votre commodité, live-build est fourni avec des scripts shell +d'exemple, pour les copier et les modifier. Lancez une nouvelle +configuration par défaut, puis copiez les exemples: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Modifiez #{auto/config}# en ajoutant des options comme bon vous semble. Par +exemple: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Maintenant, chaque fois que vous utilisez #{lb config}#, #{auto/config}# +réinitialisera la configuration basée sur ces options. Lorsque vous +souhaitez effectuer des modifications, modifiez les options dans ce fichier +au lieu de les passer à #{lb config}#. Lorsque vous utilisez #{lb clean}#, +#{auto/clean}# va nettoyer les fichiers ainsi que tous les autres produits +de construction. Et enfin, lorsque vous utilisez #{lb build}#, un journal de +la construction est écrit par #{auto/build}# dans #{build.log}#. + +*{Remarque:}* Un paramètre spécial #{noauto}# est utilisé ici pour éliminer un autre appel à #{auto/config}#, évitant ainsi une récursion infinie. Assurez-vous que vous ne l'avez pas accidentellement supprimé en modifiant le fichier. Aussi, prenez soin de vous assurer quand vous divisez la commande #{lb config}# sur plusieurs lignes pour une meilleure lisibilité, comme le montre l'exemple ci-dessus, que vous n'oubliez pas la barre oblique inverse (\) de sorte que chaque ligne continue à la suivante. + +2~clone-configuration-via-git Cloner une configuration publiée via Git + +Utilisez l'option #{lb config --config}# pour cloner un dépôt Git qui +contient une configuration d'un système live. Si vous souhaitez baser votre +configuration sur une autre maintenue par le ${project}, allez voir le dépôt +sur http://live-systems.org/gitweb avec le nom #{live-images}# sous le titre +#{Packages}#. Ce dépôt contient les configurations pour les {images +précompilées}#downloading-prebuilt-images + +Par exemple, pour construire une image standard, utilisez le dépôt +#{live-images}# comme suit: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Modifiez #{auto/config}# et toutes les autres choses dont vous avez besoin +dans l'arbre #{config}# en fonction de vos besoins. Par exemple, les images +precompilées non officielles qui contiennent paquets non-free sont faites en +ajoutant simplement #{--archive-areas "main contrib non-free"}#. + +Vous pouvez éventuellement définir un raccourci dans votre configuration Git +en ajoutant la ligne suivante à votre #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +Cela vous permet d'utiliser #{lso:}# quand vous voulez indiquer l'adresse +d'un dépôt #{live-systems.org}#. Si vous supprimez le suffixe optionnel +#{.git}#, commencer une nouvelle image en utilisant cette configuration est +aussi simple que: + +code{ + + $ lb config --config lso:live-images + +}code + +Le clonage de la totalité du dépôt #{live-images}# copie les configurations +utilisées pour plusieurs images. Si vous voulez construire une image +différente lorsque vous avez terminé avec la première, changez de répertoire +et, éventuellement, faites les modifications dont vous avez besoin. + +Dans tous les cas, n'oubliez pas qu'il faut à chaque fois construire l'image +en tant que superutilisateur: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/fr/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/fr/user_overview.ssi new file mode 100644 index 0000000..7b86230 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/fr/user_overview.ssi @@ -0,0 +1,143 @@ +:B~ Aperçu des outils + +1~overview-of-tools Aperçu des outils + +Ce chapitre fournit un aperçu des trois principaux outils utilisés dans la +construction des systèmes live: live-build, live-boot et live-config. + +2~live-build Le paquet live-build + +live-build est une collection de scripts pour construire des systèmes +live. Ces scripts sont aussi appelés "commandes". + +L'idée derrière live-build est de constituer un cadre qui utilise un +répertoire de configuration pour automatiser et personnaliser complètement +tous les aspects de la construction d'une image Live. + +Plusieurs concepts sont similaires à ceux utilisés pour construire des +paquets Debian avec /{debhelper}/: + +_* Les scripts ont un emplacement central pour la configuration de leur +fonctionnement. Avec /{debhelper}/, c'est le sous-répertoire #{debian/}# +d'un arbre de paquets. Par exemple, dh_install cherchera, entre autres, un +fichier appelé #{debian/install}# pour déterminer quels fichiers doivent +exister dans un paquet binaire particulier. De la même manière, live-build +enregistre sa configuration entièrement dans un sous-répertoire #{config/}#. + +_* Les scripts sont indépendants, c'est-à-dire qu'il est toujours sûr +d'exécuter chaque commande. + +Contrairement à /{debhelper}/, live-build contient des outils pour générer +une arborescence de configuration. Cela pourrait être considéré comme +similaire à des outils tels que /{dh-make}/. Pour plus d'informations sur +ces outils, continuer la lecture, parce que le reste de cette section est +sur les quatre commandes les plus importantes. Notez que la commande #{lb}# +est une function générique pour les commandes live-build. + +_* *{lb config}*: Responsable de l'initialisation d'un répertoire de +configuration pour un système Live. Voir {La commande lb config }#lb-config +pour plus d'informations. + +_* *{lb build}*: Responsable du démarrage d'un système de construction +Live. Voir {La commande lb build}#lb-build pour plus d'informations. + +_* *{lb clean}*: Responsable de la suppression des parties d'un système de +construction Live. Voir {La commande lb clean}#lb-clean pour plus +d'informations. + +3~lb-config La commande #{lb config}# + +Comme indiqué dans {live-build}#live-build, les scripts qui composent +live-build lisent leur configuration avec la commande #{source}# à partir +d'un seul répertoire nommé #{config/}#. Comme la construction de ce +répertoire à la main serait fastidieuse et source d'erreurs, la commande +#{lb config}# peut être utilisée pour créer une arborescence de +configuration. + +Exécuter la commande #{lb config}# sans aucun argument crée le +sous-répertoire #{config/}# qui est peuplée avec certains paramètres dans +fichiers de configuration, et deux sous-répertoires #{auto/}# et #{local/}# +avec une arborescence de fichiers. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +L'utilisation de #{lb config}# sans aucun argument serait appropriée pour +les utilisateurs qui ont besoin d'une image de base, ou qui ont l'intention +de fournir plus tard une configuration plus complète via #{auto/config}# +(voir {Gestion d'une configuration}#managing-a-configuration pour plus de +détails). + +Normalement, vous voulez indiquer certaines options. Par exemple, pour +spécifier le gestionnaire de paquets à utiliser lors de la construction de +l'image: + +code{ + + $ lb config --apt aptitude + +}code + +Il est possible d'indiquer plusieurs options, telles que: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +Une liste complète des options est disponible dans la page de manuel de +#{lb_config}#. + +3~lb-build La commande #{lb build}# + +La commande #{lb build}# lit dans votre configuration à partir du répertoire +#{config/}#. Elle exécute alors les commandes de niveau inférieur +nécessaires à la construction de votre système Live. + +3~lb-clean La commande #{lb clean}# + +Le rôle de la commande #{lb clean}# est d'enlever les différentes parties +d'une construction afin que autres compilations ultérieures puissent +commencer à partir d'un état propre. Par défaut, les étapes #{chroot}#, +#{binary}# et #{source}# sont nettoyées, mais le cache est laissé intact. En +outre, les étapes peuvent être nettoyées individuellement. Par exemple, si +vous avez effectué des changements qui affectent uniquement la phase +binaire, utilisez #{lb clean --binary}# avant de construire un nouveau +binaire. Si vos modifications invalident le bootstrap et/ou les caches de +paquets, par exemple, modifications aux options #{--mode}#, +#{--architecture}# ou #{--bootstrap}#, vous devez utiliser #{lb clean +--purge}#. Voir la page de manuel de #{lb_clean}# pour une liste complète +des options. + +2~live-boot Le paquet live-boot + +live-boot est une collection de scripts fournissant des hooks pour +/{initramfs-tools}/. Il est utilisé pour générer un initramfs capable de +démarrer des systèmes live, comme ceux créés par live-build. Cela inclut +ISOs, netboot tarballs, et les images pour clés USB. + +Au démarrage, il va chercher un support en lecture seule qui contient un +répertoire #{/live/}# où un système de fichiers racine (souvent une image du +système de fichiers compressée comme squashfs) est stocké. S'il le trouve, +il va créer un environnement accessible en écriture, en utilisant aufs, afin +que les systèmes similaires à Debian puissent démarrer à partir de cet +environnement. + +Plus d'information sur initial ramfs dans Debian peut être trouvée dans le +Debian Linux Kernel Handbook sur http://kernel-handbook.alioth.debian.org/ +dans le chapitre sur initramfs. + +2~live-config Le paquet live-config + +live-config se compose des scripts qui s'exécutent au démarrage après +live-boot pour configurer le système live automatiquement. Il gère les +tâches telles que l'établissement du nom d'hôte, des paramètres régionaux et +du fuseau horaire, la création de l'utilisateur live, l'inhibition des cron +jobs et l'autologin de l'utilisateur live. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/it/about_manual.ssi new file mode 100644 index 0000000..10c711e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/about_manual.ssi @@ -0,0 +1,271 @@ +:B~ A proposito di questo manuale + +1~about-manual A proposito di questo manuale + +This manual serves as a single access point to all documentation related to +the ${project} and in particular applies to the software produced by the +project for the Debian 9.0 "${stable}" release. An up-to-date version can +always be found at http://live-systems.org/ + +While live-manual is primarily focused on helping you build a live system +and not on end-user topics, an end user may find some useful information in +these sections: {The Basics}#the-basics covers downloading prebuilt images +and preparing images to be booted from media or the network, either using +the web builder or running live-build directly on your system. {Customizing +run time behaviours}#customizing-run-time-behaviours describes some options +that may be specified at the boot prompt, such as selecting a keyboard +layout and locale, and using persistence. + +Alcuni dei comandi menzionati nel testo devono essere eseguiti con i +privilegi di super-utente che possono essere ottenuti diventando utente root +tramite #{su}# oppure usando #{sudo}#. Per distinguere i comandi che possono +essere eseguiti come utente normale da quelli che necessitano dei privilegi +di super-utente, i comandi sono preceduti rispettivamente da #{$}# o +#{#}#. Questi simboli non fanno parte del comando. + +2~ Per gli impazienti + +Sebbene crediamo che ogni cosa in questo manuale sia importante almeno per +alcuni dei nostri utenti, ci rendiamo conto che c'è tanto materiale da +trattare e che si potrebbe voler provare il software prima di entrare nei +dettagli; pertanto suggeriamo di leggerlo nel seguente ordine. + +First, read this chapter, {About this manual}#about-manual, from the +beginning and ending with the {Terms}#terms section. Next, skip to the three +tutorials at the front of the {Examples}#examples section designed to teach +you image building and customization basics. Read {Using the +examples}#using-the-examples first, followed by {Tutorial 1: A default +image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and +finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these +tutorials, you will have a taste of what can be done with live systems. + +We encourage you to return to more in-depth study of the manual, perhaps +next reading {The basics}#the-basics, skimming or skipping {Building a +netboot image}#building-netboot-image, and finishing by reading the +{Customization overview}#customization-overview and the chapters that follow +it. By this point, we hope you are thoroughly excited by what can be done +with live systems and motivated to read the rest of the manual, +cover-to-cover. + +2~terms Glossario + +_* *{Live system}*: An operating system that can boot without installation +to a hard drive. Live systems do not alter local operating system(s) or +file(s) already installed on the computer hard drive unless instructed to do +so. Live systems are typically booted from media such as CDs, DVDs or USB +sticks. Some may also boot over the network (via netboot images, see +{Building a netboot image}#building-netboot-image), and over the Internet +(via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). + +_* *{Supporto Live}*: diversamente dal sistmea live, si riferisce a CD, DVD +o penna USB dove viene scritto il binario prodotto da live-build e usato per +l'avvio del sistema live. Più in generale, il termine si riferisce anche a +qualsiasi posto in cui risiede il binario allo scopo di avviare il sistema, +come il percorso per i file di avvio da rete. + +_* *{${project}}*: The project which maintains, among others, the live-boot, +live-build, live-config, live-tools and live-manual packages. + +_* *{Sistema host}*: l'ambiente utilizzato per creare il sistema live. + +_* *{Sistema di destinazione}*: l'ambiente usato per eseguire il sistema +live. + +_* *{live-boot}*: una raccolta di script usati per avviare sistemi live. + +_* *{live-build}*: A collection of scripts used to build customized live +systems. + +_* *{live-config}*: una raccolta di script usati per configurare un sistema +live durante il processo di avvio. + +_* *{live-tools}*: una raccolta di script aggiuntivi usati per eseguire +utili compiti in un sistema live avviato. + +_* *{live-manual}*: questo documento è inserito nel pacchetto chiamato +live-manual. + +_* *{Debian Installer (d-i)}*: il sistema d'installazione ufficiale per la +distribuzione Debian. + +_* *{Boot parameters}*: parametri che possono essere immessi nel prompt del +boot loader per modificare il comportamento del kernel o di live-config. + +_* *{chroot}*: il programma /{chroot}/, #{chroot(8)}#, rende possibile +eseguire diverse istanze dell'ambiente GNU/Linux su un singolo sistema +simultaneamente senza riavviare. + +_* *{Binary image}*: A file containing the live system, such as +live-image-i386.hybrid.iso or live-image-i386.img. + +_* *{Distribuzione di destinazione}*: la distribuzione su cui sarà basato il +sistema live. Può differire dalla distribuzione presente sul proprio +computer. + +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently +codenamed ${stable}, contains the latest officially released distribution of +Debian. The *{testing}* distribution, temporarily codenamed ${testing}, is +the staging area for the next *{stable}* release. A major advantage of using +this distribution is that it has more recent versions of software relative +to the *{stable}* release. The *{unstable}* distribution, permanently +codenamed sid, is where active development of Debian occurs. Generally, this +distribution is run by developers and those who like to live on the +edge. Throughout the manual, we tend to use codenames for the releases, such +as ${testing} or sid, as that is what is supported by the tools themselves. + +2~ Autori + +Lista degli autori (in ordine alfabetico): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contribuire a questo documento + +Questo manuale è pensato come un progetto comunitario e ogni suggerimento e +contributo è benvenuto. Si veda {Contribuire al +progetto}#contributing-to-project per informazioni dettagliate su come +prelevare la chiave SSH ed eseguire buoni commit. + +3~applying-changes Applying changes + +Per apportare modifiche alla versione inglese del manuale è necessario +modificare i file giusti in #{manual/en/}#, ma prima di sottoporre il +proprio contributo si prega di visionare l'anteprima del proprio lavoro. Per +ottenere l'anteprima di live-manual, assicurarsi di avere installato i +pacchetti necessari per la sua compilazione eseguendo: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Si può compilare il live-manual dalla directory superiore del checkout di +Git eseguendo: + +code{ + + $ make build + +}code + +Since it takes a while to build the manual in all supported languages, +authors may find it convenient to use one of the fast proofing shortcuts +when reviewing the new documentation they have added to the English +manual. Using #{PROOF=1}# builds live-manual in html format, but without the +segmented html files, and using #{PROOF=2}# builds live-manual in pdf +format, but only the A4 and letter portraits. That is why using either of +the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: + +code{ + + $ make build PROOF=1 + +}code + +When proofing one of the translations it is possible to build only one +language by executing, e.g: + +code{ + + $ make build LANGUAGES=de + +}code + +È inoltre possibile compilare in base al tipo di documento, esempio: + +code{ + + $ make build FORMATS=pdf + +}code + +O entrambi: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +Dopo aver revisionato il proprio lavoro e assicurato che tutto funzioni, non +usare #{make commit}# a meno che nel commit non si stiano aggiornando delle +traduzioni, in tal caso non mescolare nello stesso le modifiche al manuale +inglese e le traduzioni ma eseguire un commit per ognuna. Per maggiori +dettagli vedere la sezione {Traduzione}#translation. + +3~translation Traduzione + +In order to translate live-manual, follow these steps depending on whether +you are starting a translation from scratch or continue working on an +already existing one: + +_* Start a new translation from scratch + +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and +*{index.html.in.pot}* files in #{manual/pot/}# to your language with your +favourite editor (such as /{poedit}/) and send the translated #{.po}# files +to the mailing list to check their integrity. live-manual's integrity check +not only ensures that the #{.po}# files are 100% translated but it also +detects possible errors. + +_2* Once checked, to enable a new language in the autobuild it is enough to +add the initial translated files to #{manual/po/${LANGUAGE}/}# and run +#{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the +name of the language and its name in English between brackets. + +_* Continue with an already started translation + +_2* If your target language has already been added, you can randomly +continue translating the remaining .po files in #{manual/po/${LANGUAGE}/}# +using your favourite editor (such as /{poedit}/). + +_2* Do not forget that you need to run #{make commit}# to ensure that the +translated manuals are updated from the .po files and then you can review +your changes launching #{make build}# before #{git add .}#, #{git commit -m +"Translating..."}# and #{git push}#. Remember that since #{make build}# can +take a considerable amount of time, you can proofread languages individually +as explained in {Applying changes}#applying-changes + +Dopo aver eseguito #{make commit}# si vedrà del testo scorrere. Questi sono +messaggi informativi sullo stato del processo e alcuni suggerimenti su cosa +si può fare per migliorare live-manual. A meno che non si ottenga un errore +fatale si può procedere e inviare il proprio contributo. + +live-manual comes with two utilities that can greatly help translators to +find untranslated and changed strings. The first one is "make translate". It +launches an script that tells you in detail how many untranslated strings +there are in each .po file. The second one, the "make fixfuzzy" target, only +acts upon changed strings but it helps you to find and fix them one by one. + +È da considerare che nonostante queste utilità possono davvero risultare +utili per tradurre dalla riga di comando, si raccomanda l'uso di uno +strumento specifico come /{poedit}/. È inoltre una buona idea leggere la +documentazione sulla localizzazione in Debian (l10n) e, specifiche per +live-manual, le {Linee guida per i traduttori}#guidelines-translators. + +*{Nota:}* si può usare #{make clean}# per pulire l'albero del repository git locale prima del push. Grazie al file .gitignore questo passo non è obbligatorio ma è una buona abitudine che evita di fare involontariamente il commit di certi file. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/it/about_project.ssi new file mode 100644 index 0000000..e373027 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/about_project.ssi @@ -0,0 +1,104 @@ +:B~ About the ${project} + +1~about-project About the ${project} + +2~ Motivazioni + +3~ Cosa c'è di sbagliato con gli attuali sistemi live + +When ${project} was initiated, there were already several Debian based live +systems available and they are doing a great job. From the Debian +perspective most of them have one or more of the following disadvantages: + +_* Non sono progetti Debian, per cui non sono supportati da Debian. + +_* Mischiano differenti distribuzioni come ad esempio: *{testing}* e +*{unstable}*. + +_* Supportano solamente i386. + +_* Modificano l'aspetto e il comportamento dei pacchetti snellendoli per +risparmiare spazio. + +_* Includono pacchetti esterni all'archivio Debian. + +_* Forniscono un kernel con patch addizionali che non appartengono a Debian. + +_* Sono grandi e lenti a causa delle loro dimensioni e non adatti per +operazioni di salvataggio. + +_* Non sono disponibili in diversi formati come CD, DVD, penne USB e +immagini netboot. + +3~ Perché creare il proprio sistema live? + +Debian è il Sistema Operativo Universale, ha un sistema live per mostrare e +rappresentare accuratamente il sistema con i seguenti vantaggi: + +_* È un sottoprogetto di Debian. + +_* Riflette lo stato (attuale) di una distribuzione. + +_* Gira su più architetture possibili. + +_* È costituito solo da pacchetti Debian non modificati. + +_* Non contiene nessun pacchetto che non sia presente nell'archivio di +Debian. + +_* Usa un kernel Debian inalterato senza patch addizionali. + +2~ Filosofia + +3~ Solamente pacchetti da Debian "main", inalterati. + +Verranno usati solo pacchetti dal repository Debian della sezione "main".La +sezione non-free non è parte di Debian perciò non possono essere +affattousati per le immagini ufficiali del sistema live. + +Non verrà cambiato nessun pacchetto. Nel caso in cui sarà necessario +cambiare qualcosa sarà fatto in coordinazione con il maintainer del +pacchetto Debian. + +In via eccezionale i nostri pacchetti come live-boot, live-build o +live-config possono temporaneamente essere usati dal nostro repository per +ragioni di sviluppo (ad esempio per creare istantanee). Verranno caricati +regolarmente in Debian. + +3~ Nessun pacchetto di configurazione per il sistema live + +In questa fase non saranno disponibili né esempi di installazione né +configurazioni alternative. Tutti i pacchetti vengono usati con la loro +configurazione predefinita così come accade con una regolare installazione +di Debian. + +Nel caso in cui serva una configurazione predefinita differente, sarà fatto +in coordinazione con il maintainer del pacchetto in Debian. + +A system for configuring packages is provided using debconf allowing custom +configured packages to be installed in your custom produced live system +images, but for the {prebuilt live images}#downloading-prebuilt-images we +choose to leave packages in their default configuration, unless absolutely +necessary in order to work in the live environment. Wherever possible, we +prefer to adapt packages within the Debian archive to work better in a live +system versus making changes to the live toolchain or {prebuilt image +configurations}#clone-configuration-via-git. For more information, please +see {Customization overview}#customization-overview. + +2~contact Contatti + +_* *{Mailing list}*: il principale contatto del progetto è la mailing list +https://lists.debian.org/debian-live/, si possono inviare email alla lista +direttamente a debian-live@lists.debian.org. Gli archivi sono disponibili +presso https://lists.debian.org/debian-live/. + +_* *{IRC}*: molti utenti e sviluppatori sono presenti sul canale +#debian-live su irc.debian.org (OFTC). Quando si pone una domanda su IRC, si +prega di essere pazienti nell'ottenere una risposta; se non si riceve +risposta scrivere alla mailing list. + +_* *{BTS}*: il {Debian Bug Tracking System}https://www.debian.org/Bugs/ +(BTS) contiene i dettagli dei bug riportati dagli utenti e dagli +sviluppatori. A ciascun bug viene assegnato un numero, e viene mantenuto +finché non è segnato come risolto. Per ulteriori informazioni si veda +{Segnalare bug}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/it/appendix_style-guide.ssi new file mode 100644 index 0000000..1bba13e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/appendix_style-guide.ssi @@ -0,0 +1,364 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account +when writing technical documentation for live-manual. They are divided into +linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers +of English. So as a general rule try to use short, meaningful sentences, +followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a +suggestion to try to avoid, as much as possible, complex subordinate +sentences that make the text difficult to understand for non-native speakers +of English. + +_* /{Variety of English}/ + +The most widely spread varieties of English are British and American so it +is very likely that most authors will use either one or the other. In a +collaborative environment, the ideal variety would be "International +English" but it is very difficult, not to say impossible, to decide on which +variety among all the existing ones, is the best to use. + +We expect that different varieties may mix without creating +misunderstandings but in general terms you should try to be coherent and +before deciding on using British, American or any other English flavour at +your discretion, please take a look at how other people write and try to +imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely +unrelated to live-manual. Technical writing should be as neutral as +possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make +references to the third person singular preferably use "they" rather than +"he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +Go straight to the point and do not wander around aimlessly. Give as much +information as necessary but do not give more information than necessary, +this is to say, do not explain unnecessary details. Your readers are +intelligent. Presume some previous knowledge on their part. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several +other languages. This implies that a number of people will have to do an +extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +As suggested before, it is almost impossible to standardize a collaborative +document into a perfectly unified whole. However, every effort on your side +to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Be descriptive}/ + +It is preferable to describe the point in one or several paragraphs than +merely using a number of sentences in a typical "changelog" style. Describe +it! Your readers will appreciate it. + +_* /{Dictionary}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not +know how to express certain concepts in English. But keep in mind that a +dictionary can either be your best friend or can turn into your worst enemy +if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million +words). Many of these words are borrowings from other languages. When +looking up the meaning of words in a bilingual dictionary the tendency of a +non-native speaker of English is to choose the one that sounds more similar +in their mother tongue. This often turns into an excessively formal +discourse which does not sound quite natural in English. + +As a general rule, if a concept can be expressed using different synonyms, +it is a good advice to choose the first word proposed by the dictionary. If +in doubt, choosing words of Germanic origin (Usually monosyllabic words) is +often the right thing to do. Be warned that these two techniques might +produce a rather informal discourse but at least your choice of words will +be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely +helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search +engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign +language you cannot help falling from time to time in the trap of the so +called "false friends", words that look similar in two languages but whose +meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may +convey a completely different meaning from what their individual words seem +to mean. Sometimes, idioms might be difficult to understand even for native +speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical +writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand +and above all contractions that try to imitate the spoken language. Not to +mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +It is important that authors test their examples before adding them to +live-manual to ensure that everything works as described. Testing on a clean +chroot or VM can be a good starting point. Besides, it would be ideal if the +tests were then carried out on different machines with different hardware to +spot possible problems that may arise. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, +after all, just an example. + +It is often better to use a line that only applies to a specific case than +using abstractions that may confuse your readers. In this case you can +provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some +potentially dangerous commands that, if misused, may cause data loss or +other similar undesirable effects. In this case you should provide a +thorough explanation of the possible side effects. + +_* /{External links}/ + +Links to external sites should only be used when the information on those +sites is crucial when it comes to understanding a special point. Even so, +try to use links to external sites as sparsely as possible. Internet links +are likely to change from time to time resulting in broken links and leaving +your arguments in an incomplete state. + +Besides, people who read the manual offline will not have the chance to +follow those links. + +_* /{Avoid branding and things that violate the license under which the +manual is published}/ + +Try to avoid branding as much as possible. Keep in mind that other +downstream projects might make use of the documentation you write. So you +are complicating things for them if you add certain specific material. + +live-manual is licensed under the GNU GPL. This has a number of implications +that apply to the distribution of the material (of any kind, including +copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence + of events. + + - Once you have somehow organized those ideas in your mind write a first + draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names + of the releases, such as ${testing} or sid, should not be capitalized + when referred to as code names. In order to check the spelling you can + run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, +1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup +below. + +If you have to enumerate a series of steps or stages in your description, +you can also use ordinal numbers: First, second, third ... or First, Then, +After that, Finally ... Alternatively you can use bulleted items. + +_* /{Markup}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to +process the text files and produce a multiple format output. It is +recommended to take a look at {SiSU's +manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get +familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to +highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to +remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account +when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the +translation rules that apply to their specific languages. Usually, +translation groups and mailing lists provide information on how to produce +translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +The role of the translator is to convey as faithfully as possible the +meaning of words, sentences, paragraphs and texts as written by the original +authors into their target language. + +So they should refrain from adding personal comments or extra bits of +information of their own. If they want to add a comment for other +translators working on the same documents, they can leave it in the space +reserved for that. That is, the header of the strings in the *{po}* files +preceded by a number sign *{#}*. Most graphical translation programs can +automatically handle those types of comments. + +_* /{TN, Translator's Note}/ + +It is perfectly acceptable however, to include a word or an expression in +brackets in the translated text if, and only if, that makes the meaning of a +difficult word or expression clearer to the reader. Inside the brackets the +translator should make evident that the addition was theirs using the +abbreviation "TN" or "Translator's Note". + +_* /{Impersonal sentences}/ + +Documents written in English make an extensive use of the impersonal form +"you". In some other languages that do not share this characteristic, this +might give the false impression that the original texts are directly +addressing the reader when they are actually not doing so. Translators must +be aware of that fact and reflect it in their language as accurately as +possible. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to +translators. Double check the meaning of suspicious false friends if in +doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* +files will find many markup features in the strings. They can translate the +text anyway, as long as it is translatable, but it is extremely important +that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in +the translation is the only way to score a 100% complete translation. And +even though it means more work at first because it might require the +intervention of the translators if the code changes, it is the best way, in +the long run, to identify what has already been translated and what has not +when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original +texts. Be careful to press the "Enter" key or type *{\n}* if they appear in +the original files. These newlines often appear, for instance, in the code +blocks. + +Make no mistake, this does not mean that the translated text needs to have +the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths diff --git a/markup/pod-samples/pod/live-manual/media/text/it/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/it/examples.ssi new file mode 100644 index 0000000..e15848d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/examples.ssi @@ -0,0 +1,447 @@ +:B~ Esempi + +1~examples Esempi + +This chapter covers example builds for specific use cases with live +systems. If you are new to building your own live system images, we +recommend you first look at the three tutorials in sequence, as each one +teaches new techniques that will help you use and understand the remaining +examples. + +2~using-the-examples Usare gli esempi + +Per usare questi esempi è necessario un sistema per costruirveli sopra che +soddisfi i requisiti elencati in {Requisiti}#requirements e avere live-build +installato come descritto in {Installare live-build}#installing-live-build. + +È da notare che per brevità in questi esempi non specifichiamo un mirror +locale da usare per la costruzione. Usando un mirror locale, si possono +accelerare considerevolmente i download. Si possono specificare le opzioni +quando si usa #{lb config}#, come descritto in {Mirror delle distribuzioni +usati in fase di compilazione}#distribution-mirrors-build-time o, più +convenientemente, impostare il predefinito per il proprio sistema in +#{/etc/live/build.conf}#. Si crei semplicemente questo file e si impostino +in esso le corrispondenti variabili #{LB_MIRROR_*}# per il mirror +desiderato. Tutti gli altri mirror utilizzati nella costruzione avranno +questi valori, ad esempio: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-updates/" + +}code + +2~tutorial-1 Tutorial 1: un'immagine predefinita + +*{Caso d'uso:}* creazione di una prima semplice immagine, imparando i fondamenti di live-build. + +In this tutorial, we will build a default ISO hybrid live system image +containing only base packages (no Xorg) and some live system support +packages, as a first exercise in using live-build. + +Non può essere più semplice: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Esaminare i contenuti della directory #{config/}#; si noterà uno scheletro +di configurazione pronto per essere personalizzato o, in questo caso, usato +immediatamente per costruire un'immagine predefinita. + +Ora, come utente root, generare l'immagine salvando un log con #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Assuming all goes well, after a while, the current directory will contain +#{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly +in a virtual machine as described in {Testing an ISO image with +Qemu}#testing-iso-with-qemu and {Testing an ISO image with +VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media +or a USB flash device as described in {Burning an ISO image to a physical +medium}#burning-iso-image and {Copying an ISO hybrid image to a USB +stick}#copying-iso-hybrid-to-usb, respectively. + +2~tutorial-2 Tutorial 2: servizio browser web + +*{Caso d'uso:}* creazione di un'immagine per servizio browser web, imparando come applicare le personalizzazioni. + +In this tutorial, we will create an image suitable for use as a web browser +utility, serving as an introduction to customizing live system images. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +La scelta di LXDE per questo esempio riflette il desiderio di fornire un +ambiente desktop minimale, dato che il punto focale dell'immagine è il +singolo uso che abbiamo in mente, il browser web. Potremmo anche spingerci +oltre e fornire una configurazione predefinita per il browser web in +#{config/includes.chroot/etc/iceweasel/profile/}#, o pacchetti addizionali +di supporto per la fruizione di vari tipi di contenuti web, ma lasciamo +questo come esercizio per il lettore. + +Generare l'immagine, ancora come utente root, conservando un log come in +{Tutorial 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Di nuovo, verificare che l'immagine sia a posto e collaudarla, come in +{Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: un'immagine personalizzata + +*{Caso d'uso:}* creazione di un progetto per costruire un'immagine personalizzata che contiene i pacchetti preferiti da portare con sé in una chiavetta USB ovunque si vada, e che evolve in revisioni successive allorché i bisogni o le preferenze cambino. + +Dal momento che la nostra immagine personalizzata cambierà con le successive +revisioni e che vogliamo tener traccia di questi cambiamenti, andando per +tentativi ed eventualmente tornando indietro se qualcosa non funziona, +conserveremo la nostra configurazione nel popolare sistema di controllo di +versione #{git}#. Useremo anche le migliori pratiche di auto-configurazione +tramite gli script #{auto}# come descritto in {Gestire una +configurazione}#managing-a-configuration. + +3~ Prima revisione + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Modificare #{auto/config}# come segue: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Eseguire #{lb config}# per generare l'albero di configurazione utilizzando +lo script #{auto/config}# appena creato: + +code{ + + $ lb config + +}code + +Popolare ora l'elenco locale dei pacchetti: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +Per prima cosa, #{--architectures i386}# assicura che sul nostro sistema +#{amd64}# costruiamo una versione a 32-bit utilizzabile sulla maggior parte +delle macchine. In secondo luogo, usiamo #{--linux-flavours 686-pae}# dato +che non prevediamo di usare questa immagine su sistemi troppo vecchi. Terzo, +abbiamo scelto il metapacchetto task /{lxde}/ per avere un desktop +minimale. Infine abbiamo aggiunto due pacchetti preferiti: /{iceweasel}/ e +/{xchat}/. + +Costruire quindi l'immagine: + +code{ + + # lb build + +}code + +Notare che diversamente dai primi due tutorial non occorre più digitare +#{2>&1 | tee build.log}# dato che questo è ora incluso in #{auto/build}#. + +Una volta che l'immagine è stata collaudata (come in {Tutorial +1}#tutorial-1) e che si è sicuri che funzioni correttamente, è il momento di +inizializzare il repository #{git}#, aggiungendo solo gli script auto appena +creati, e di fare poi il primo commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Seconda revisione + +In questa revisione ripuliremo la prima compilazione, aggiungeremo il +pacchetto /{vlc}/ alla configurazione, dunque avverrà una ricompilazione, +verifica e commit. + +Il comando #{lb clean}# ripulirà tutti i file ottenuti con la precedente +generazione eccetto la cache, che ci evita un nuovo download dei +pacchetti. Ciò assicura che il successivo #{lb build}# eseguirà di nuovo +tutti i passaggi per rigenerare i file dalla nuova configurazione. + +code{ + + # lb clean + +}code + +Ora inserire il pacchetto /{vlc}/ all'elenco locale dei pacchetti +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Rigenerare nuovamente: + +code{ + +# lb build + +}code + +Verificare e, quando soddisfatti, eseguire il commit della revisione +successiva: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Ovviamente sono possibili cambiamenti alla configurazione più complicati, +magari aggiungendo file in sottodirectory di #{config/}#. Quando si esegue +il commit di nuove revisioni, si faccia solo attenzione a non modificare +manualmente o fare un commit dei file al livello superiore di #{config}# che +contengono le variabili #{LB_*}#, giacché sono anche prodotti +dell'assemblaggio, e che sono sempre ripuliti da #{lb clean}# e ricreati con +#{lb config}# attraverso i loro rispettivi script #{auto}#. + +We've come to the end of our tutorial series. While many more kinds of +customization are possible, even just using the few features explored in +these simple examples, an almost infinite variety of different images can be +created. The remaining examples in this section cover several other use +cases drawn from the collected experiences of users of live systems. + +2~ Un client Kiosk VNC + +*{Caso d'uso:}* creazione di un'immagine con live-build per avviare direttamente un server VNC. + +Creare una directory per la compilazione e una configurazione di base al suo +interno disabilitando i raccomandati per ottenere un sistema +minimale. Quindi creare due elenchi di pacchetti: il primo generato con uno +script fornito da live-build chiamato #{Packages}# (vedere {Elenchi di +pacchetti generati}#generated-package-lists) e il secondo che include +/{xorg}/, /{gdm3}/, /{metacity}/ e /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +Come spiegato in {Modificare APT per risparmiare +spazio}#tweaking-apt-to-save-space potrebbe essere necessario riaggiungere +alcuni pacchetti raccomandati al fine di far funzionare l'immagine +correttamente. + +Un modo semplice per elencare i raccomandati è usare /{apt-cache}/, ad +esempio: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +In questo esempio abbiamo scoperto che dobbiamo iserire nuovamente svariati +pacchetti raccommandati da live-config e live-boot: #{user-setup}# perché il +login automatico funzioni e #{sudo}# come programma essenziale per spegnere +il sistema. Oltretutto può essere comodo aggiungere #{live-tools}# per poter +copiare l'immagine in RAM e #{eject}# per espellere il supporto live alla +fine. Quindi: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +Successivamente creare la directory #{/etc/skel}# in +#{config/includes.chroot}# e inserirvi un #{.xsession}# personalizzato per +l'utente predefinito che lancerà /{metacity}/ e avvierà /{xvncviewer}/ +connesso alla porta #{5901}# su un server con indirizzo #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Compilare l'immagine: + +code{ + + # lb build + +}code + +Buon divertimento. + +2~ Un'immagine base per una chiavetta USB da 128MB + +*{Caso d'uso:}* creazione di un'immagine predefinita con alcuni componenti rimossi affinché possa stare su una chiavetta USB da 128MB, con un po' di spazio libero da usarsi come meglio si crede. + +Quando si cerca di ottimizzare un'immagine affinché sia contenuta in un +supporto, è necessario capire il compromesso che si deve fare tra la +dimensione e la funzionalità. In questo esempio, taglieremo solo quanto +basta per far sì che il tutto stia in 128M, senza fare nient'altro che +distrugga l'integrità dei pacchetti contenuti, come eliminare localizzazioni +con il pacchetto /{localepurge}/ o altre ottimizzazioni "intrusive". È da +notare che per creare un sistema minimale da zero viene utilizzata l'opzione +#{--debootstrap-options}#. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +Affinché l'immagine funzioni correttamente dobbiamo riaggiungere almeno due +pacchetti raccomandati lasciati fuori dall'opzione #{--apt-recommends +false}#. Vedere {Modificare APT per risparmiare +spazio}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Costruire quindi l'immagine nel modo consueto: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration +produced a 110MB image. This compares favourably with the 192MB image +produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount +of space, the tradeoff being that you need to do an #{apt-get update}# +before using /{apt}/ in the live system. Dropping recommended packages with +#{--apt-recommends false}# saves some additional space, at the expense of +omitting some packages you might otherwise expect to be +there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal +system from the start. Not automatically including firmware packages with +#{--firmware-chroot false}# saves some space too. And finally, #{--memtest +none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ Un desktop GNOME localizzato e l'installatore + +*{Caso d'uso:}* creazione di un'immagine con il desktop GNOME, localizzato in svizzero e che includa l'installatore. + +Si vuole creare un'immagine iso ibrida per architettura i386 usando il +nostro desktop preferito, in questo caso GNOME, contenente tutti gli stessi +pacchetti che verrebbero installati dall'installatore Debian standard per +GNOME. + +Il problema iniziale è di scoprire i nomi dei task della lingua appropriati, +attualmente, live-build non aiuta in questo. Si può essere fortunati o +arrivarci con vari tentativi, ma c'è uno strumento #{grep-dctrl}# il quale +può essere utilizzato per scavare nelle descrizioni in tasksel-data, perciò +assicursi di avere entrambi questi pacchetti: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Ora si possono cercare i task appropriati: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +Con questo comando, si è chiaramente scoperto che il task si chiama +german. Ora per trovare i task correlati: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +Durante il boot verrà generata la localizzazione *{de_CH.UTF-8}* e +selezionato il layout di tastiera *{ch}, mettiamo ora insieme questi +pezzi. Ricordando che i metapacchetti task iniziano con #{task-}# (come +descritto in {Usare metapacchetti}#using-metapackages), specifichiamo questi +parametri d'avvio per la lingua, quindi aggiungiamo i pacchetti con priorità +standard e tutti i metapacchetti task al nostro elenco in questo modo: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to +launch the installer from the live desktop. The #{586}# kernel flavour, +which is currently necessary for the launcher to work properly, will be +included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/it/live-manual.ssm new file mode 100644 index 0000000..b401b21 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manuale di Live Systems" + +creator: + author: "Live Systems Project <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "Questo programma è software libero: è possibile ridistribuirlo e modificarlo secondo i termini della GNU General Public License come pubblicata dalla Free Software Foundation, sia la versione 3 della licenza o (a scelta) una versione successiva. \\ \\ Questo programma è distribuito nella speranza che possa essere utile, ma SENZA ALCUNA GARANZIA, nemmeno la garanzia implicita di COMMERCIABILITÀ o IDONEITÀ PER UN PARTICOLARE SCOPO. Vedere la GNU General Public License per ulteriori dettagli. \\ \\ Si dovrebbe aver ricevuto una copia della GNU General Public License con questo programma. In caso contrario, vedere http://www.gnu.org/licenses/. \\ \\ Il testo completo della GNU General Public License può essere trovato nel file /usr/share/common-licenses/GPL-3." + +date: + published: "2015-08-23" + +publisher: "Live Systems Project <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ A proposito + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Utente + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Progetto + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Esempi + +<< examples.ssi + +:B~ Appendice + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/it/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/it/project_bugs.ssi new file mode 100644 index 0000000..1b3fbc4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/project_bugs.ssi @@ -0,0 +1,210 @@ +:B~ Segnalare bug + +1~bugs Segnalare bug + +Live systems are far from being perfect, but we want to make it as close as +possible to perfect - with your help. Do not hesitate to report a bug. It is +better to fill a report twice than never. However, this chapter includes +recommendations on how to file good bug reports. + +Per gli impazienti + +_* Per i problemi noti verificare sempre lo stato degli aggiornamenti +dell'immagine sulla nostra pagina iniziale http://live-systems.org/. + +_* Before submitting a bug report always try to reproduce the bug with the +*{most recent versions}* of the branch of live-build, live-boot, live-config +and live-tools that you're using (like the newest 4.x version of live-build +if you're using live-build 4). + +_* Si cerchi di fornire *{informazioni il più dettagliate possibile}* +riguardo il bug. Questo comprende (almeno) la versione di live-build, +live-boot, live-config e live-tools utilizzata e la distribuzione del +sistema live che si sta creando. + +2~ Problemi noti + +Giacché Debian *{testing}* e Debian *{unstable}* subiscono cambiamenti +continui, quando si specifica l'una o l'altra come sistema di destinazione, +può non essere sempre possibile una compilazione che vada a buon fine. + +% FIXME: + +Se questo causa troppe difficoltà, non creare un sistema basato su +*{testing}* o *{unstable}* ma usare piuttosto *{stable}*. live-build si basa +su *{stable}* in modo predefinito. + +I problemi noti al momento sono elencati sotto la sezione "status" della +nostra pagina iniziale http://live-systems.org/ + +Questo manuale non intende insegnare come identificare e risolvere +correttamente i problemi dei pacchetti delle distribuzioni di sviluppo, +tuttavia ci sono un paio di cose da provare: se la creazione di *{testing}* +non va a buon fine provare con *{unstable}*; se non funziona nemmeno +*{unstable}* tornare a *{testing}* ed effettuare il pinning da *{unstable}* +alla nuova versione del pacchetto corrotto (si veda {APT +pinning}#apt-pinning per i dettagli). + +2~ Ricompilare da zero + +Per essere certi che un particolare bug non sia causato dalla creazione di +un sistema non pulito, ricostruire sempre l'intero sistema da zero per +vedere se il bug sia riproducibile. + +2~ Usare pacchetti aggiornati + +L'utilizzo di pacchetti datati può causare notevoli complicazioni nel +tentativo di riprodurre (e alla fine risolvere) il problema. Assicurarsi che +il sistema creato sia aggiornato e ogni pacchetto incluso nell'immagine lo +sia a sua volta. + +2~collect-information Raccogliere informazioni + +Nella segnalazione si invita a fornire informazioni sufficienti. Dovrebbe +almeno contenere l'esatta versione di live-build nella quale si è trovato il +bug e i passi per riprodurlo. Con un po' di buon senso si può includere +qualsiasi altro dettaglio rilevante che si ritiene utile per la risoluzione +del problema. + +Affinché la segnalazione del bug sia migliore possibile, si richiedono +almeno le seguenti informazioni: + +_* Architettura del sistema ospitante + +_* Distribution of the host system + +_* Versione di live-build sul sistema ospitante + +_* Version of /{debootstrap}/ on the host system + +_* Architettura del sistema live + +_* Distribuzione del sistema live + +_* Versione di live-boot sul sistema ospitante + +_* Versione di live-config sul sistema live + +_* Versione di live-tools sul sistema ospitante + +È possibile generare un registro del processo di costruzione usando il +comando #{tee}#. Si raccomanda di farlo automaticamente con uno script +#{auto/build}#; (si veda {Gestire una +configurazione}#managing-a-configuration per i dettagli). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +All'avvio, live-boot e live-config conservano i loro registri in +#{/var/log/live/}#. Controllarvi gli errori. + +Inoltre, per escludere altri errori è sempre una buona idea creare un tar +della propria directory #{config/}# e caricarlo da qualche parte (*{non}* +inviarlo come allegato alla mailing list), in modo che sia per noi possibile +riprodurre gli errori incontrati. Se ciò causa problemi (ad esempio a causa +della dimensione) si può utilizzare l'output di #{lb config --dump}# che +produce un sommario dell'albero di configurazione (elenca i file nelle +sottodirectory di #{config/}# ma non le include). + +Ricordarsi che i file di registro da inviare vanno creati con l'impostazione +della lingua inglese, ad esempio eseguendo il comando live-build preponendo +#{LC_ALL=C}# oppure #{LC_ALL=en_US}#. + +2~ Se possibile isolare il caso non andato a buon fine + +Se possibile, isolare il caso non andato a buon fine alla variazione più +piccola che lo causa. Non è sempre facile da fare, perciò non preoccupatevi +se non riuscite a gestirlo per la vostra segnalazione. Tuttavia, se si +pianifica bene il ciclo di sviluppo adottando piccole modifiche per ogni +iterazione, si riuscirà ad isolare il problema creando una configurazione +semplificata che si avvicina all'attuale con l'aggiunta delle sole modifiche +problematiche. Se si incontrano serie difficoltà nel trovare la causa, +potrebbe essere che sono stati inseriti troppi cambiamenti in una sola volta +e bisogna cambiare approccio. + +2~ Segnalare il bug del pacchetto giusto + +Se non si sa quale sia il componente responsabile del bug o se il bug è uno +generico riguardante il sistema live, si può fare una segnalazione per lo +pseudo-pacchetto debian-live. + +Tuttavia vi saremmo grati se tentate di restringere il campo in base a dove +appare il bug. + +3~ Durante la compilazione mentre esegue il bootstrap + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a +bug appears here, check if the error is related to a specific Debian package +(most likely), or if it is related to the bootstrapping tool itself. + +In both cases, this is not a bug in the live system, but rather in Debian +itself and probably we cannot fix it directly. Please report such a bug +against the bootstrapping tool or the failing package. + +3~ Durante la compilazione mentre installa i pacchetti + +live-build installa pacchetti aggiuntivi dall'archivio Debian e può fallire +a seconda della distribuzione Debian e lo stato dell'archivio giornaliero.Se +il bug appare a questo punto, controllare che l'errore sia riproducibile su +un sistema normale. + +If this is the case, this is not a bug in the live system, but rather in +Debian - please report it against the failing package. Running +/{debootstrap}/ separately from the Live system build or running #{lb +bootstrap --debug}# will give you more information. + +Se si verifica un problema utilizzando un mirror locale o un qualsiasi tipo +di proxy è bene riprodurlo avviando da un mirror ufficiale. + +3~ In fase di avvio + +Se l'immagine non si avvia segnalarlo alla mailing list con le informazioni +richieste in {Raccogliere informazioni}#collect-information. Non dimenticare +di menzionare esattamente come e quando l'immagine fallisce, utilizzando la +virtualizzazione o hardware reale. Se si utilizza un qualsiasi sistema di +virtualizzazione provare sempre su hardware reale prima di segnalare un bug; +anche fornire un'istantanea dello schermo può essere molto utile. + +3~ In fase di esecuzione + +If a package was successfully installed, but fails while actually running +the Live system, this is probably a bug in the live system. However: + +2~ Fare la ricerca + +Prima di riportare il bug si prega di cercare sul web il messaggio d'errore +o il sintomo ottenuti. Poiché è altamente improbabile essere l'unica persona +ad incontrare un certo problema, c'è sempre la possibilità che sia stato +discusso altrove e che siano stati proposte una soluzione, una patch o +soluzione temporanea. + +You should pay particular attention to the live systems mailing list, as +well as the homepage, as these are likely to contain the most up-to-date +information. If such information exists, always include the references to it +in your bug report. + +In aggiunta bisogna controllare l'attuale elenco dei bug riguardanti +live-build, live-boot, live-config e live-tools per vedere se sia già stato +segnalato qualcosa di simile. + +2~ Dove segnalare i bug + +The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For +information on how to use the system, please see +https://bugs.debian.org/. You can also submit the bugs by using the +#{reportbug}# command from the package with the same name. + +In genere bisogna riportare gli errori in fase di compilazione verso il +pacchetto live-build, quelli di avvio verso live-boot e quelli in fase di +esecuzione a live-config. Se non siete certi di quale sia il pacchetto +appropriato o serve maggiore aiuto prima della segnalazione, inviate una +segnalazione per lo pseudo-pacchetto debian-live. Ce ne occuperemo +riassegnandolo dove più appropriato. + +Si noti che i bug trovati nelle distribuzioni derivate da Debian (come +Ubuntu e altre) *{non}* vanno segnalati a Debian BTS a meno che non siano +riproducibili anche su un sistema Debian utilizzando pacchetti ufficiali +Debian. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/it/project_coding-style.ssi new file mode 100644 index 0000000..8cee468 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/project_coding-style.ssi @@ -0,0 +1,151 @@ +:B~ Lo stile nello scrivere codice + +1~coding-style Lo stile nello scrivere codice + +This chapter documents the coding style used in live systems. + +2~ Compatibilità + +_* Non usare sintassi o semantiche mirate alla shell Bash. Ad esempio l'uso +di costrutti array. + +_* Utilizzare solo il sottoinsieme POSIX - ad esempio, usare $(foo) invece +di `foo`. + +_* È possibile verificare i propri script con "sh -n" e "checkbashisms". + +Assicurarsi che tutto il codice giri con 'set -e'. + +2~ Rientri + +_* Usare sempre i tab piuttosto che gli spazi. + +2~ Ritorno a capo + +_* Generalmente le righe sono composte da un massimo di 80 caratteri. + +_* Utilizzare lo "stile Linux" per le interruzioni di riga: + +Sbagliato: + +code{ + + if foo; then + bar + fi + +}code + +Corretto: + +code{ + + if foo + then + bar + fi + +}code + +_* Lo stesso vale per le funzioni: + +Sbagliato: + +code{ + + Foo () { + bar + } + +}code + +Corretto: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variabili + +_* Le variabili vanno sempre scritte in maiuscolo. + +_* Le variabili usate in live-build iniziano sempre con il prefisso #{LB_}#. + +_* Le variabili interne temporanee in live-build dovrebbero iniziare con il +prefisso #{\_LB_}#. + +_* Le variabili locali iniziano con il prefisso live-build #{\_\_LB_}#. + +_* Le variabili in live-config relative ai parametri di avvio iniziano con +#{LIVE_}#. + +_* Tutte le altre variabili in live-config iniziano con il prefisso #{_}#. + +_* Intorno alle variabili utilizzare le graffe; ad esempio scrivere +#{${FOO}}# invece di #{$FOO}#. + +_* Proteggere sempre le variabili con le virgolette per rispettare +potenziali spaziature: scrivere #{"${FOO}"}# e non #{${FOO}}#. + +_* Per coerenza usare sempre le virgolette quando si assegnano valori alle +variabili: + +Sbagliato: + +code{ + + FOO=bar + +}code + +Corretto: + +code{ + + FOO="bar" + +}code + +_* Utilizzando variabili multiple, quotare l'intera espressione: + +Sbagliato: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Corretto: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Varie + +_* Per le chiamate a sed utilizzare "#{|}#" (senza virgolette intorno) come +separatore, ad esempio "#{sed -e 's|foo|bar|'}#" (senza ""). + +_* Non utilizzare il comando #{test}# per prove o confronti, usare "#{[}#" +"#{]}#" (senza ""); ad esempio "#{if [ -x /bin/foo ]; ...}#" e non "#{if +test -x /bin/foo; ...}#". + +_* Ove possibile utilizzare #{case}# invece di #{test}#, essendo più facile +da leggere e più veloce in esecuzione. + +_* Per le funzioni utilizzare nomi che iniziano con la maiuscola per +limitare i problemi con le variabili d'ambiente dell'utente. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/it/project_contributing.ssi new file mode 100644 index 0000000..4144c7c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/project_contributing.ssi @@ -0,0 +1,117 @@ +:B~ Contribuire al progetto + +1~contributing-to-project Contribuire al progetto + +When submitting a contribution, please clearly identify its copyright holder +and include any applicable licensing statement. Note that to be accepted, +the contribution must be licensed under the same license as the rest of the +documents, namely, GPL version 3 or later. + +I contributi al progetto, come traduzioni e patch, sono estremamente +benvenuti. Chiunque può eseguire il commit direttamente sul repository; +tuttavia chiediamo di inviare le modifiche più corpose in mailing list, per +poterne prima discutere. Per maggiori informazioni vedere la sezione +{Contatti}#contact. + +The ${project} uses Git as version control system and source code +management. As explained in {Git repositories}#git-repositories there are +two main development branches: *{debian}* and *{debian-next}*. Everybody can +commit to the debian-next branches of the live-boot, live-build, +live-config, live-images, live-manual and live-tools repositories. + +Tuttavia ci sono alcune restrizioni. Il server rifiuta: + +_* push non fast-forward, + +_* commit merge, + +_* aggiunta o rimozione di tag e branch. + +Anche se tutti i commit possono essere corretti, chiediamo di usare il buon +senso ed eseguire buoni commit con dei buoni messaggi. + +_* Si scrivano messaggi costituiti da frasi in inglese esaurienti e utili, +inizianti con una lettera maiuscola e terminanti con un punto. Solitamente +cominceranno con la forma +"Fixing/Adding/Removing/Correcting/Translating/...". + +_* Scrivere buoni messaggi nei commmit. La prima riga deve contenere un +sunto accurato del contenuto del commit in quanto verrà incluso nel +changelog. Se si necessita di aggiungere ulteriori spiegazioni, scriverle +sotto lasciando una riga vuota dopo la prima e quindi un'altra vuota dopo +ogni paragrafo. Le righe non devono superare gli 80 caratteri. + +_* Eseguire commit atomici, ovvero non mescolare cose non inerenti tra loro +nello stesso commit ma farne uno per ogni modifica apportata. + +2~ Applicare le modifiche + +Per eseguire il push ai repository è necessario seguire la seguente +procedura. Verrà usato live-manual come esempio per cui rimpiazzalo con il +nome del repository su cui si vuole lavorare. Per informazioni dettagliare +su come modificare live-manual si veda {Contribuire a questo +documento}#how-to-contribute. + +_* Prelevare la chiave pubblica: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Aggiungere la seguente sezione alla propria configurazione di +openssh-client: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Scaricare tramite ssh un clone del manuale: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Assicurarsi di avere impostato autore e indirizzo email: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Importante:}* Notare che tutte le modifiche vanno eseguite sul ramo *{debian-next}*. + +_* Apportare le modifiche. In questo esempio si scrive prima una nuova +sezione che si occupa di applicare patch e quindi prepararla al commit +aggiungendo i file e scrivendo il messaggio in questo modo: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Inviare il commit al server: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/it/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/it/project_git.ssi new file mode 100644 index 0000000..de2d438 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/project_git.ssi @@ -0,0 +1,87 @@ +:B~ Repository Git + +1~git-repositories Repository Git + +The list of all the available repositories of the ${project} can be found at +http://live-systems.org/gitweb/. The project's git URLs have the form: +#{protocol://live-systems.org/git/repository}#. Thus, in order to clone +live-manual read-only, launch: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +oppure + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +oppure + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +The cloning addresses with write permission have the form: +#{git@live-systems.org:/repository}#. + +Quindi per clonare live-manual via ssh si userà: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +Il ramo git del progetto Debian Live è costituito da molteplici branch +differenti. I branch *{debian}* e *{debian-next}* sono particolarmente degni +di nota in quanto contengono il lavoro attuale che verrà incluso in ogni +nuovo rilascio. + +Dopp aver clonato uno dei repository esistenti sarete nel branch +*{debian}*.Questo è adatto per prendere visione dello stato dell'ultimo +rilascio del progetto ma prima di iniziare a lavorarci è cruciale passare a +*{debian-next}*. Per farlo eseguire: + +code{ + + $ git checkout debian-next + +}code + +Il branch *{debian-next}*, che non è sempre soggetto al fast-forward, è dove +si fa il commit di tutte le modifiche prima di essere incluse nel branch +*{debian}*. È come un terreno di test, per fare un analogia. Se si sta +lavorando in questo branch e si necessita di eseguire il pull, bisogna usare +#{git pull --rebase}# in modo che le modifiche locali siano preparate per il +commit (stage) quando si fa il pull dal server, in questo modo saranno poste +in cima a tutto il resto. + +2~ Gestire repository multipli + +If you intend to clone several of the live systems repositories and want to +switch to the *{debian-next}* branch right away to check the latest code, +write a patch or contribute with a translation you ought to know that the +git server provides a #{mrconfig}# file to ease the handling of multiple +repositories. In order to use it you need to install the /{mr}/ package and +after that, launch: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +Il comando clonerà e farà il checkout al ramo *{debian-next}* dei repository +di sviluppo dei pacchetti Debian prodotti dal progetto. Questi includono tra +gli altri il repository live-images che contiene le configurazioni usate per +le immagini precompilate che il progetto pubblica per uso generico. Per +maggiori informazioni su come utilizzare questo repository si veda {Clonare +una configurazione pubblicata tramite Git.}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/it/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/it/project_procedures.ssi new file mode 100644 index 0000000..a347fa9 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/project_procedures.ssi @@ -0,0 +1,101 @@ +:B~ Procedure + +1~procedures Procedure + +This chapter documents the procedures within the ${project} for various +tasks that need cooperation with other teams in Debian. + +2~ Rilasci importanti + +Rilasciare una nuova versione stabile di Debian implica che molti team +differenti lavorino insieme; ad un certo punto si inserisce il team Live che +prepara le immagini del sistema live. I requisiti per fare ciò sono: + +_* Un mirror contenente le versioni rilasciate per l'archivio debian e +debian-security al quale possa accedere il debian-live buildd. + +_* Vanno resi noti i nomi dell'immagine +(debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* Bisogna sincronizzare i dati dal cd Debian (gli udeb escludono gli +elenchi). + +_* Le immagini vengono create e ospitate su cdimage.debian.org. + +2~ Rilasci minori + +_* Bisogna nuovamente aggiornare i mirror di debian e debian-security. + +_* Le immagini vengono create e ospitate su cdimage.debian.org. + +_* Inviare email di annuncio. + +3~ Ultimo rilascio minore di un rilascio di Debian. + +Quando si crea l'ultima serie di immagini per un rilascio di Debian che è +stato spostato da ftp.debian.org a archive.debian.org, ricordarsi di +sistemare i mirror del chroot e dei binari. In questo modo le vecchie +immagini live create saranno ancora utili senza la necessità di modifiche da +parte dell'utente. + +3~ Modello per l'annuncio di un rilascio minore. + +Si può generare un'email per l'annuncio dei rilasci minori usando il modello +sottostante e il seguente comando: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Si prega di controllare attentamente l'email prima di inviarla e passarla ad +altri per le correzioni. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_basics.ssi new file mode 100644 index 0000000..83695e8 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_basics.ssi @@ -0,0 +1,632 @@ +:B~ Nozioni di base + +1~the-basics Nozioni di base + +This chapter contains a brief overview of the build process and instructions +for using the three most commonly used image types. The most versatile image +type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or +USB portable storage device. In certain special cases, as explained later, +the #{hdd}# type may be more suitable. The chapter includes detailed +instructions for building and using a #{netboot}# type image, which is a bit +more involved due to the setup required on the server. This is an slightly +advanced topic for anyone who is not already familiar with netbooting, but +it is included here because once the setup is done, it is a very convenient +way to test and deploy images for booting on the local network without the +hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting +which is, perhaps, the easiest way of using different images for different +purposes, switching from one to the other as needed using the internet as a +means. + +In tutto il capitolo faremo spesso riferimento ai nomi dei file predefiniti +creati da live-build. Se invece si {scarica un'immagine +precompilata}#downloading-prebuilt-images, i nomi possono variare. + +2~what-is-live Cos'è un sistema live? + +Per sistema live generalmente si intende un sistema operativo che può essere +avviato da un supporto rimovibile, come un CD-ROM o una chiavetta USB oppure +da una rete, pronto per l'uso senza alcuna installazione su hard disk con +una configurazione automatica fatta durante l'esecuzione (vedere +{Glossario}#terms). + +With live systems, it's an operating system, built for one of the supported +architectures (currently amd64 and i386). It is made from the following +parts: + +_* *{Immagine del kernel Linux}*, comunemente chiamata #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd)}*: un disco RAM creato per il boot di +Linux, contenente i moduli potenzialmente necessari per montare l'immagine +di sistema e alcuni script per farlo. + +_* *{System image}*: The operating system's filesystem image. Usually, a +SquashFS compressed filesystem is used to minimize the live system image +size. Note that it is read-only. So, during boot the live system will use a +RAM disk and 'union' mechanism to enable writing files within the running +system. However, all modifications will be lost upon shutdown unless +optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: una piccola porzione di codice predisposto per l'avvio +dal supporto scelto, che presenta un prompt o un menu per la selezione di +opzioni/configurazioni. Carica il kernel Linux ed il suo initrd da eseguire +con un filesystem associato. Possono essere usate diverse soluzioni, in base +al supporto di destinazione ed al formato del filesystem contenenti le +componenti precedentemente citate: isolinux per il boot da CD o DVD nel +formato ISO9660, syslinux per supporti HDD o USB che si avviano da una +partizione VFAT, extlinux per le partizioni ext/2/3/4 e btrfs, pxelinux per +il netboot PXE, GRUB per partizioni ext2/3/4, ecc. + +È possibile usare live-build per creare l'immagine di sistema secondo le +proprie specifiche, scegliere un kernel Linux, il suo initrd ed un +bootloader per avviarli, tutto in un unico formato che dipende dal mezzo +(immagini ISO9660, immagine disco, ecc.) + +2~downloading-prebuilt-images Scaricare immagini precompilate + +Nonostante l'obiettivo di questo manuale è di sviluppare e creare le proprie +immagini live si potrebbe semplicemente voler provare una di quelle +precompilate, sia come introduzione al loro uso o per costruirne una +propria. Queste immagini sono create utilizzando il nostro {repository git +live-imagesy}#clone-configuration-via-git e i rilasci ufficiali di stable +pubblicati all'indirizzo https://www.debian.org/CD/live/. In aggiunta, +all'indirizzo http://live-systems.org/cdimage/release/ sono disponibili le +versioni vecchie e future e le immagini non ufficiali contenenti firmware e +driver non-free. + +2~using-web-builder Utilizzare il web builder per le immagini live + +As a service to the community, we run a web-based live image builder service +at http://live-systems.org/build/. This site is maintained on a best effort +basis. That is, although we strive to keep it up-to-date and operational at +all times, and do issue notices for significant operational outages, we +cannot guarantee 100% availability or fast image building, and the service +may occasionally have issues that take some time to resolve. If you have +problems or questions about the service, please {contact us}#contact, +providing us with the link to your build. + +3~ Utilizzo del web builder e raccomandazioni + +The web interface currently makes no provision to prevent the use of invalid +combinations of options, and in particular, where changing an option would +normally (i.e. using live-build directly) change defaults of other options +listed in the web form, the web builder does not change these defaults. Most +notably, if you change #{--architectures}# from the default #{i386}# to +#{amd64}#, you must change the corresponding option #{--linux-flavours}# +from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for +the version of live-build installed on the web builder for more details. The +version number of live-build is listed at the bottom of the web builder +page. + +Le tempistiche fornite dal web builder sono solo una stima approssimata e +possono non riflettere quanto realmente ci vorrà per compilare, né vengono +aggiornate una volta apparse. Vi preghiamo di essere pazienti e di non +aggiornare la pagina dopo aver commissionato la compilazione in quanto +invierà la richiesta per una nuova operazione con gli stessi parametri. Se, +dopo aver aspettato a sufficienza e verificato che l'email non sia finita +nello spam, non ricevete alcuna notifica allora {contattateci}#contact. + +Il web builder ha un limite di tipologie di immagini creabili, mantenendosi +semplice e efficiente da utilizzare e manutenere. Le personalizzazioni non +sono fornite dall'interfaccia web, il resto di questo manuale sipega come +creare le proprie immagini tramite live-build. + +2~building-iso-hybrid Primi passi: creare un'immagine ISO ibrida + +Indipendentemente dal tipo di immagine, per crearne una è necessario +eseguire ogni volta la stessa procedura. Come primo esempio si creerà una +directory di lavoro, vi si entrerà e si eseguirà la seguente sequenza di +comandi di live-build per creare un'immagine ISO ibrida di base contenente +un sistema live predefinito senza X.org. È adatta per essere masterizzata su +CD o DVD e anche per essere copiata su una penna USB. + +Il nome della directory di lavoro è arbitrario ma guardando gli esempi usati +da live-manual è una buona idea utilizzare un nome che aiuta a identificare +in qualsiasi directory l'immagine su cui si sta lavorando, in particolar +modo se si stanno sperimentando tipi di di immagine differenti. In questo +caso stiamo creando un sistema predefinito quindi chiamiamolo ad esempio +live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy +in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their +various options will be used. See {The lb config command}#lb-config for more +details. + +Ora che si ha una gerarchia "config/" si può generare l'immagine con il +comando #{lb build}#: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and +your network connection. When it is complete, there should be a +#{live-image-i386.hybrid.iso}# image file, ready to use, in the current +directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Utilizzare un'immagine ISO live ibrida + +Dopo aver costruito o scaricato un'immagine ISO ibrida, ottenibile +all'indirizzo https://www.debian.org/CD/live/, il passo successivo è +preparare il supporto per l'avvio, che sia esso un CD-R(W), un DVD-R(W) o +una penna USB. + +3~burning-iso-image Masterizzare un'immagine ISO su un supporto fisico + +Masterizzare un'immagine ISO è semplice, basta installare /{xorriso}/ e +utilizzarlo da riga di comando; ad esempio: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copiare un'immagine ISO ibrida su una penna USB + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick +with the #{cp}# program or an equivalent. Plug in a USB stick with a size +large enough for your image file and determine which device it is, which we +hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, +such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find +the right device name by looking in #{dmesg}#'s output after plugging in the +stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# +command to copy the image to the stick. *{This will definitely overwrite +any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Usare lo spazio rimanente su una penna USB + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first +partition on the device will be filled up by the live system. To use the +remaining free space, use a partitioning tool such as /{gparted}/ or +/{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +Dopo aver creato la partizione, dove #{${PARTITION}}# è il nome della +partizione, ad esempio #{/dev/sdb2}#, si deve creare su di essa un +filesystem. Una scelta possibile potrebbe essere ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Nota:}* se si desidera utilizzare lo spazio extra con Windows pare che questo sistema operativo non possa accedere a nessuna partizione eccetto la prima. Alcune soluzioni a questo problema sono state discusse sulla nostra {mailing list}#contact, ma non sembrano esserci risposte semplici. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-media Avviare il supporto live + +La prima volta che si avvia il supporto live, CD, DVD, penna USB o PXE, può +essere necessario impostare il BIOS del computer, ma giacché questi variano +parecchio in opzioni e scorciatoie, non siamo in grado di +descriverli. Alcuni BIOS offrono un menu per selezionare il device in fase +di boot, in caso sia disponibile nel vostro sistema è il modo più +semplice. Altrimenti è necessario accedere alla sua configurazione e +modificare l'ordine di avvio per posizionare la periferica di boot del +sistema live prima di quella usuale. + +Avviando il supporto si otterrà un menu, premendo il tasto enter il sistema +partirà utilizzando la voce #{Live}# e le opzioni predefinite. Per ulteriori +informazioni sulle opzioni di boot, si veda la voce "help" nel menu e le +pagine di manuale di live-boot e live-config all'interno del sistema. + +Assuming you've selected #{Live}# and booted a default desktop live image, +after the boot messages scroll by, you should be automatically logged into +the #{user}# account and see a desktop, ready to use. If you have booted a +console-only image, such as a #{standard}# flavour {prebuilt +image}#downloading-prebuilt-images, you should be automatically logged in on +the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Utilizzare una macchina virtuale per le prove + +Per lo sviluppo delle immagini live, può essere un notevole risparmio di +tempo eseguirle in una macchina virtuale (VM). Non senza qualche +raccomandazione: + +_* Eseguire una VM richiede un quantitativo sufficiente di RAM sia per il +sistema ospitato che per quello ospitante; è consigliato un processore che +gestisca la virtualizzazione a livello hardware. + +_* Ci sono alcune limitazioni inerenti, quali uno scarso rendimento video e +una scelta limitata di hardware emulato. + +_* Quando si sviluppa per un hardware specifico non vi è alcun sostituto +migliore del proprio hardware. + +_* Occasionalmente possono esserci dei bug relativi al solo utilizzo di una +VM. Nel dubbio si provi l'immagine direttamente sul proprio hardware. + +A condizione che si possa lavorare entro questi vincoli, cercare il software +disponibile per la virtualizzazione e scegliere quello adatto alle proprie +necessità. + +3~testing-iso-with-qemu Provare un'immagine ISO con QEMU + +Il programma più versatile in Debian è QEMU. Se il processore gestisce la +virtualizzazione hardware utilizzare il pacchetto /{qemu-kvm}/; la +descrizione elenca brevemente i requisiti. + +Per prima cosa installare /{qemu-kvm}/ o altrimenti /{qemu}/, nel qual caso +il nome del programma nei successivi sarà #{qemu}# invece di #{kvm}#. Il +pacchetto /{qemu-utils}/ è inoltre utile per creare immagini di dischi +virtuali con #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Avviare un'immagine ISO è semplice: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +Per maggiori dettagli si vedano le pagine di manuale. + +3~testing-iso-with-virtualbox Testing an ISO image with VirtualBox + +Per provare la ISO con /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use +#{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Nota:}* per sistemi live contenenti X.org che si vogliono provare con /{virtualbox}/, si può voler includere il pacchetto dei driver per X.org di VirtualBox, /{virtualbox-guest-dkms}/ e /{virtualbox-guest-x11}/, nella configurazione di live-build. In caso contrario la risoluzione è limitata a 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +Per far funzionare il pacchetto dkms vanno anche installati gli header per +il kernel utilizzato nell'immagine. Anziché indicare manualmente il +pacchetto /{linux-headers}/ adeguato nell'elenco dei pacchetti creato prima, +la selezione può essere fatta automaticamente da live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Creare e utilizzare un'immagine HDD + +Building an HDD image is similar to an ISO hybrid one in all respects except +you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# +which cannot be burnt to optical media. It is suitable for booting from USB +sticks, USB hard drives, and various other portable storage +devices. Normally, an ISO hybrid image can be used for this purpose instead, +but if you have a BIOS which does not handle hybrid images properly, you +need an HDD image. + +*{Nota:}* se si è creata un'immagine ISO ibrida con gli esempi precedenti, occorre pulire la directory di lavoro con il comando #{lb clean}# (vedere {Il comando lb clean}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Eseguire il comando #{lb config}# come prima, questa volta specificando però +il tipo di immagine HDD: + +code{ + + $ lb config -b hdd + +}code + +Creare ora l'immagine con il comando #{lb build}#: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in +the current directory. + +The generated binary image contains a VFAT partition and the syslinux +bootloader, ready to be directly written on a USB device. Once again, using +an HDD image is just like using an ISO hybrid one on USB. Follow the +instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except +use the filename #{live-image-i386.img}# instead of +#{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described +above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run +#{kvm}# or #{qemu}#, depending on which version your host system needs, +specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Creare un'immagine netboot + +La seguente sequenza di comandi creerà un'immagine netboot di base +contenente un sistema live predefinito senza X.org. È adatta per il boot +tramite rete. + +*{Nota:}* se qualcuno tra gli esempi precedenti è stato seguito, bisogna pulire la directory di lavoro con il comando #{lb clean}#: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean +up the necessary stages. The cause for this is that in netboot setups, a +different initramfs configuration needs to be used which live-build performs +automatically when building netboot images. Since the initramfs creation +belongs to the chroot stage, switching to netboot in an existing build +directory means to rebuild the chroot stage too. Therefore, #{lb clean}# +(which will remove the chroot stage, too) needs to be used. + +Per configurare l'immagine per l'avvio da rete, eseguire il comando #{lb +config}# come segue: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +Diversamente dalle immagini ISO e HDD, il boot via rete non fornisce +un'immagine del filesytem al client, perciò i file devono essere forniti via +NFS. Con lb config si possono scegliere filesystem di rete diefferenti. Le +opzioni #{--net-root-path}# e #{--net-root-server}# specificano, +rispettivamente, il percorso e il server del server NFS dove l'immagine del +filesystem sarà situata all'avvio. Accertarsi che questi siano impostati su +valori adeguati alla propria rete. + +Creare ora l'immagine con il comando #{lb build}#: + +code{ + + # lb build + +}code + +In un avvio tramite rete, il client esegue una piccola parte di software che +normalmente risiede sulla EPROM della scheda Ethernet. Questo programma +invia una richiesta DHCP per ottenere un indirizzo IP e le informazioni su +cosa fare in seguito. In genere il passo successivo è ottenere un bootloader +di di livello superiore attraverso il protocollo TFTP. Questi potrebbe +essere pxelinux, GRUB, o anche avviare direttamente un sistema operativo +come Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# +archive in the #{/srv/debian-live}# directory, you'll find the filesystem +image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux +bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the +DHCP server, the TFTP server and the NFS server. + +3~ Server DHCP + +Si deve configurare il server DHCP della rete per essere sicuri di fornire +un indirizzo IP al sistema client che si avvia tramite rete, e notificare la +posizione del bootloader PXE. + +Ecco un esempio, scritto per un server DHCP ISC #{isc-dhcp-server}# nel file +di configurazione #{/etc/dhcp/dhcpd.conf}#: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Server TFTP + +Fornisce al sistema il kernel e il ramdisk iniziale in fase di esecuzione. + +Si installi il pacchetto /{tftpd-hpa}/, che mette a disposizione tutti i +file contenuti in una directory root, di solito #{/srv/tftp}#. Affinché si +possa disporre dei file contenuti in #{/srv/debian-live/tftpboot}#, eseguire +il seguente comando come utente root: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +e inserire la nuova directory del server tftp quando richiesto. + +3~ Server NFS + +Una volta che il computer ospite ha scaricato e avviato un kernel Linux e +caricato il suo initrd, cercherà di montare l'immagine del filesystem Live +tramite un server NFS. + +Bisogna installare il pacchetto /{nfs-kernel-server}/. + +Quindi, rendere disponibile l'immagine del filesystem via NFS aggiungendo +una riga come la seguente in #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +e comunicare il nuovo export al server NFS con il seguente comando: + +code{ + + # exportfs -rv + +}code + +Configurare questi tre servizi può essere un po' problematico, serve un +attimo di pazienza per farli funzionare assieme. Per ulteriori informazioni +vedere il wiki syslinux http://www.syslinux.org/wiki/index.php/PXELINUX o il +manuale del Debian Installer alla sezione per l'avvio TFTP da rete +http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. Ciò può essere +d'aiuto, considerato che il procedimento è molto simile. + +3~ Come provare una netboot + +La creazione di immagini netboot è resa semplice da live-build, ma provare +le immagini su una macchina reale può essere davvero dispendioso in termini +di tempo. + +Per semplificarsi il vita si può usare la virtualizzazione. + +3~ Qemu + +_* Installare /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Modificare #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Procurarsi o compilare #{grub-floppy-netboot}#. + +Lanciare #{qemu}# con "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using +the internet as a means. The requirements for webbooting are very few. On +the one hand, you need a medium with a bootloader, an initial ramdisk and a +kernel. On the other hand, a web server to store the squashfs files which +contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which +are available on the project's homepage at http://live-systems.org/. Using +prebuilt images would be handy for doing initial testing until one can fine +tune their own needs. If you have built a live image you will find the files +needed for webbooting in the build directory under #{binary/live/}#. The +files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso +image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific +case, it would be #{/mnt/live/}#. This method has the disadvantage that you +need to be root to be able to mount the image. However, it has the advantage +that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image +and uploading it to the web server at the same time, is using the midnight +commander or /{mc}/. If you have the /{genisoimage}/ package installed, the +two-pane file manager allows you to browse the contents of an iso file in +one pane and upload the files via ftp in the other pane. Even though this +method requires manual work, it does not require root privileges. + +3~ Booting webboot images + +While some users will prefer virtualization to test webbooting, we refer to +real hardware here to match the following possible use case which should +only be considered as an example. + +In order to boot a webboot image it is enough to have the components +mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a +directory named #{live/}# and install syslinux as bootloader. Then boot from +the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot +options. live-boot will retrieve the squashfs file and store it into +ram. This way, it is possible to use the downloaded compressed filesystem as +a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-binary.ssi new file mode 100644 index 0000000..5b3db08 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-binary.ssi @@ -0,0 +1,65 @@ +:B~ Personalizzare l'immagine binaria + +1~customizing-binary Personalizzare l'immagine binaria + +2~ Bootloader + +live-build usa /{syslinux}/ e alcuni dei suoi derivati (a seconda del tipo +di immagine) come bootloader predefiniti. Si possono facilmente +personalizzare per soddisfare le proprie esigenze. + +Per utilizzare un tema completo, copiare +#{/usr/share/live/build/bootloaders}# in #{config/bootloaders}# e modificare +i file. Se non si vogliono modificare tutte le configurazioni dei bootloader +supportati è sufficiente fornire la copia locale di uno di essi, ad esempio +*{isolinux}* in #{config/bootloaders/isolinux}# può bastare, dipende dalle +esigenze. + +When modifying one of the default themes, if you want to use a personalized +background image that will be displayed together with the boot menu, add a +splash.png picture of 640x480 pixels. Then, remove the splash.svg file. + +Quando si tratta di fare modifiche ci sono varie possibilità. Per esempio i +derivati di syslinux sono configurati con un timeout impostato a 0 (zero) in +modo predefinito, significa che resteranno in pausa al loro splash screen +fino a quando non si preme un tasto. + +Per modificare il timeout di avvio di un'immagine #{iso-hybrid}# modificare +un file *{isolinux.cfg}* predefinito specificando il timeout in unità di +1/10 di secondo. Un file *{isolinux.cfg}* modificato per effettuare il boot +dopo cinque secondi sarebbe simile a questo: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ Metadati ISO + +Quando si crea un'immagine binaria ISO9660, si possono usare le seguenti +opzioni per aggiungere vari metadati testuali. Questo può aiutare a +identificare facilmente la versione o la configurazione di un'immagine senza +avviarla. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: descrive l'applicazione +che sarà nell'immagine. La lunghezza massima per questo campo è di 128 +caratteri. + +* #{LB_ISO_PREPARER/--iso-preparer NAME}#: descrive il costruttore +dell'mmagine, solitamente con alcuni dettagli per +contattarlo. L'impostazione predefinita è la versione di live-build che si +sta usando, il quale potrà essere utile in seguito per il debugging. La +lunghezza massima per questo campo è di 128 caratteri. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: descrive l'editore +dell'immagine, solitamente con qualche dettaglio per contattarlo. La +lunghezza massima lunghezza per questo campo è di 128 caratteri. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: specifica l'ID del volume +dell'immagine. Questa è utilizzata come etichetta visibile all'utente su +alcune piattaforme, come Windows e Apple Mac OS. La lunghezza massima per +questo campo è di 128 caratteri. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-contents.ssi new file mode 100644 index 0000000..79092f0 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-contents.ssi @@ -0,0 +1,135 @@ +B~ Personalizzazione dei contenuti + +1~customizing-contents Personalizzazione dei contenuti + +This chapter discusses fine-tuning customization of the live system contents +beyond merely choosing which packages to include. Includes allow you to add +or replace arbitrary files in your live system image, hooks allow you to +execute arbitrary commands at different stages of the build and at boot +time, and preseeding allows you to configure packages when they are +installed by supplying answers to debconf questions. + +2~includes Include + +While ideally a live system would include files entirely provided by +unmodified packages, it is sometimes convenient to provide or modify some +content by means of files. Using includes, it is possible to add (or +replace) arbitrary files in your live system image. live-build provides two +mechanisms for using them: + +_* Include locali del chroot: permettono di aggiungere o sostituire file al +file system chroot/Live. Vedere {Live/chroot include +locali}#live-chroot-local-includes per maggiori informazioni. + +_* Include locali binari: permettono di aggiungere o sostituire file +nell'immagine binaria. Vedere {Include locali binari}#binary-local-includes +per maggiori informazioni + +Si consulti il {Glossario}#terms per ulteriori informazioni sulla +distinzione tra immagini "Live" e "binarie". + +3~live-chroot-local-includes Live/chroot include locali + +Gli include locali del chroot possono essere usati per aggiungere o +sostituire file nel filesystem chroot/Live in modo che possano essere +utilizzati nel sistema live. Un utilizzo tipico è popolare la directory +scheletro dell'utente (#{/etc/skel}#) che il sistema impiega per creare la +home dell'utente. Un altro è quello di fornire file di configurazione che +possono essere semplicemente aggiunti o sostituiti nell'immagine senza +elaborazione; si veda {Live/chroot hook locali}#live-chroot-local-hooks se è +necessaria l'elaborazione. + +Per includere i file si aggiungano semplicemente alla directory +#{config/includes.chroot}#. Questa corrisponde alla directory root #{/}# del +sistema live. Per esempio, per aggiungere un file #{/var/www/index.html}# +nel sistema live, si usi: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +La configurazione avrà quindi il seguente schema: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Gli include locali del chroot vengono installati dopo l'installazione dei +pacchetti in modo che tali file vengano in seguito sovrascitti. + +3~binary-local-includes Include locali binari + +Si possono utilizzare include locali binari per inserire sul filesystem del +supporto materiale come documentazione o video affinché sia immediatamente +accessibile dopo l'inserimento dello stesso senza avviare il sistema +live. Ciò funziona in modo simile agli include locali del chroot; supponendo +che i file #{~/video_demo.*}# siano video dimostrativi del sistema descritti +da e collegati a una pagina HTML indice, basta copiare il materiale in +#{config/includes.binary/}# come segue: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +Questi file appariranno nella directory principale del supporto live. + +2~hooks Hook + +Gli hook permettono di eseguire comandi nel chroot e nelle fasi binarie +della creazione al fine di personalizzare l'immagine. + +3~live-chroot-local-hooks Live/chroot hook locali + +To run commands in the chroot stage, create a hook script with a +#{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run in the chroot after the rest of your chroot +configuration has been applied, so remember to ensure your configuration +includes all packages and files your hook needs in order to run. See the +example chroot hook scripts for various common chroot customization tasks +provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy +or symlink to use them in your own configuration. + +3~boot-time-hooks Hook in fase di avvio + +Per eseguire comandi all'avvio, è possibile fornire degli hook a live-config +come spiegato nella sezione "Customization" del suo manuale. Controllare gli +hook di live-config in #{/lib/live/config/}# e notare i numeri sequenziali; +fornire quindi i propri hook con una sequenza numerica appropriata, sia come +include locali del chroot in #{config/includes.chroot/lib/live/config/}#, +sia come pacchetto personalizzato come discusso in{Installare pacchetti +modificati o di terze parti}#installing-modified-or-third-party-packages. + +3~ Hook binari locali + +To run commands in the binary stage, create a hook script with a +#{.hook.binary}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run after all other binary commands are run, but +before binary_checksums, the very last binary command. The commands in your +hook do not run in the chroot, so take care to not modify any files outside +of the build tree, or you may damage your build system! See the example +binary hook scripts for various common binary customization tasks provided +in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or +symlink to use them in your own configuration. + +2~ Preconfigurare le domande di Debconf + +I file nella directory #{config/preseed/}# con suffisso #{.cfg}# seguiti +dalla fase (#{.chroot}# o #{.binary}#) sono considerati file di +preconfigurazione di debconf e sono installati da live-build usando +#{debconf-set-selections}# durante la fase corrispondente. + +Per ulteriori informazioni su debconf, vedere #{debconf(7)}# nel pacchetto +/{debconf}/. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-installer.ssi new file mode 100644 index 0000000..f0ec96d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-installer.ssi @@ -0,0 +1,87 @@ +:B~ Personalizzare l'Installatore Debian + +1~customizing-installer Personalizzare l'Installatore Debian + +Live system images can be integrated with Debian Installer. There are a +number of different types of installation, varying in what is included and +how the installer operates. + +In questa sezione si presti attenzione all'uso delle lettere maiuscole +quando si fa riferimento all'"Installatore Debian", quando usato ci si +riferisce esclusivamente all'installatore ufficiale Debian. Spesso è +abbreviato come "d-i". + +2~ Tipologie dell'Installatore Debian + +I tre principali tipi dell'installer sono: + +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". + +In queste immagini, Debian è installata prendendo e installando i pacchetti +.deb usando /{debootstrap}/, da supporti locali o dalla rete, risultante in +un sistema Debian standard installato sul disco rigido. + +L'intero processo può essere preimpostato e personalizzato in diversi modi; +per ulteriori informazioni si vedano le corrispondenti pagine del manuale +dell'Installatore Debian. Una volta che si ha un file preimpostato +funzionante, live-build può inserirlo automaticamente nell'immagine e +abilitarlo. + +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. + +L'installazione procederà nello stesso modo di un'installazione "Normale" +come descritto sopra, ma nella fase dell'installazione del pacchetto, invece +di usare /{debootstrap}/ per prelevare e installare i pacchetti, l'immagine +del filesystem live viene copiata sulla destinazione. Questo si ottiene con +uno speciale udeb chiamato live-installer. + +Dopo questa fase, l'Installatore Debian continua normalmente, installando e +configurando elementi come bootloader e utenti locali, ecc. + +*{Nota:}* per supportare nel bootloader sia la voce normale che quella live dell'installatore sullo stesso supporto si deve disabilitare live-installer preconfigurando #{live-installer/enable=false}#. + +*{Installatore Debian "Desktop"}*: indipendentemente dal tipo di Installatore Debian incluso, #{d-i}# può essere lanciato cliccando un'icona sul desktop, in alcune situazioni più semplice per l'utente. Per poterne usufruire deve essere incluso il pacchetto debian-installer-launcher. + +Si noti che live-build non include l'Installatore Debian nell'immagine in +modo predefinito, necessita di essere espressamente abilitato con #{lb +config}#.Inoltre, affinché l'installatore "Desktop" funzioni, il kernel del +sistema live deve corrispondere a quello usato dal #{d-i}# per +l'architettura specificata. Per esempio: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Personalizzare il Debian Installer con la preconfigurazione + +Come descritto nell'appendice B del manuale dell'Installatore Debian +all'indirizzo https://www.debian.org/releases/stable/i386/apb.html, "La +preconfigurazione fornisce un modo per impostare le risposte alle domande +poste durante il processo d'installazione senza la necessità di inserirle +manualmente. Ciò permette di automatizzare totalmente molti tipi di +installazione offrendo anche alcune caratteristiche normalmente non +disponibili." Questo tipo di personalizzazione è compiuta in modo ottimale +con live-build mettendo la configurazione in un file #{preseed.cfg}# incluso +in #{config/includes.installer/}#. Ad esempio per preconfigurare +l'impostazione della localizzazione su #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Personalizzare il contenuto dell'Installatore Debian + +For experimental or debugging purposes, you might want to include locally +built #{d-i}# component udeb packages. Place these in +#{config/packages.binary/}# to include them in the image. Additional or +replacement files and directories may be included in the installer initrd as +well, in a similar fashion to {Live/chroot local +includes}#live-chroot-local-includes, by placing the material in +#{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-overview.ssi new file mode 100644 index 0000000..36fed62 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-overview.ssi @@ -0,0 +1,77 @@ +B~ Personalizzazione dei contenuti + +1~customization-overview Panoramica sulla personalizzazione + +This chapter gives an overview of the various ways in which you may +customize a live system. + +2~ Configurazione in fase di compilazione e di avvio + +La configurazione del sistema live è divisa in opzioni applicate in fase di +compilazione e al momento dell'avvio. Le opzioni di compilazione sono +ulteriormente divise in quelle che si verificano prima dell'avvio, applicate +dal pacchetto live-boot, e quelle dopo l'avvio, applicate da +live-config. Qualsiasi opzione in fase di avvio può essere modificata +dall'utente specificandola al prompt di avvio. L'immagine può inoltre essere +costruita con i parametri di avvio predefiniti in modo che quando tutti i +valori predefiniti sono adatti gli utenti possano avviare direttamente il +sistema senza specificare alcuna opzione. In particolare, l'argomento di +#{lb --bootappend-live}# è costituito da tutte le opzioni da riga di comando +del kernel predefinite in un sistema live, come persistenza dei dati, layout +di tastiera o fuso orario. Per gli esempi si veda {Personalizzare +localizzazione e lingua}#customizing-locale-and-language. + +Build-time configuration options are described in the #{lb config}# man +page. Boot-time options are described in the man pages for live-boot and +live-config. Although the live-boot and live-config packages are installed +within the live system you are building, it is recommended that you also +install them on your build system for easy reference when you are working on +your configuration. It is safe to do so, as none of the scripts contained +within them are executed unless the system is configured as a live system. + +2~stages-of-the-build Fasi della creazione + +Il processo di creazione è diviso in due fasi, con varie personalizzazioni +applicate in sequenza a ciascuna di esse. La prima consiste nell'*{avvio}*, +questa è la fase iniziale di popolamento della directory di chroot con i +pacchetti atti a creare un sistema Debian di base. Viene quindi seguita +dalla fase *{chroot}* che completa la costruzione della directory chroot e +la popola con tutti i pacchetti elencati nella configurazione insieme a +qualsiasi altro materiale; la maggior parte della personalizzazione dei +contenuti avviene in questa tappa. La parte finale della preparazione +dell'immagine è la fase *{binaria}* che genera un'immagine avviabile +utilizzando i contenuti della directory chroot per costruire il file system +pricipale per il sistema live, includere l'installatore e ogni altro +materiale aggiuntivo sul supporto di destinazione al di fuori del file +system del sistema live. Una volta che l'immagine è pronta viene creato, se +abilitato, l'archivio dei sorgenti nella fase *{sorgenti}*. + +All'interno di ciascuna di queste fasi c'è una sequenza particolare in cui +vengono applicati i comandi, sono organizzati in modo da assicurare che le +personalizzazioni siano ragionevolmente stratificate. Ad esempio, nella fase +*{chroot}* i preseed vengono applicati prima che qualsiasi pacchetto sia +installato, i pacchetti vengono installati prima che qualsiasi file incluso +localmente venga copiato e gli hook eseguiti dopo che tutto il materiale è a +posto. + +2~ Integrare la configurazione di lb con dei file + +Although #{lb config}# creates a skeletal configuration in the #{config/}# +directory, to accomplish your goals, you may need to provide additional +files in subdirectories of #{config/}#. Depending on where the files are +stored in the configuration, they may be copied into the live system's +filesystem or into the binary image filesystem, or may provide build-time +configurations of the system that would be cumbersome to pass as +command-line options. You may include things such as custom lists of +packages, custom artwork, or hook scripts to run either at build time or at +boot time, boosting the already considerable flexibility of debian-live with +code of your own. + +2~ Personalizzazione dei compiti + +I capitoli seguenti sono costituiti dai tipi di compito personalizzato che +gli utenti eseguono solitamente: {personalizzare l'installazione dei +pacchetti}#customizing-package-installation, {personalizzare i +contenuti}#customizing-contents e {personalizzare localizzazione e +lingua}#customizing-locale-and-language coprono solo alcune delle cose che +si potrebbero desiderare. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-packages.ssi new file mode 100644 index 0000000..df3e991 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-packages.ssi @@ -0,0 +1,652 @@ +:B~ Personalizzare l'installazione dei pacchetti + +1~customizing-package-installation Personalizzare l'installazione dei +pacchetti + +Perhaps the most basic customization of a live system is the selection of +packages to be included in the image. This chapter guides you through the +various build-time options to customize live-build's installation of +packages. The broadest choices influencing which packages are available to +install in the image are the distribution and archive areas. To ensure +decent download speeds, you should choose a nearby distribution mirror. You +can also add your own repositories for backports, experimental or custom +packages, or include packages directly as files. You can define lists of +packages, including metapackages which will install many related packages at +once, such as packages for a particular desktop or language. Finally, a +number of options give some control over /{apt}/, or if you prefer, +/{aptitude}/, at build time when packages are installed. You may find these +handy if you use a proxy, want to disable installation of recommended +packages to save space, or need to control which versions of packages are +installed via APT pinning, to name a few possibilities. + +2~ Sorgenti dei pacchetti + +3~ Distribuzione, le aree di archivio e le modalità + +The distribution you choose has the broadest impact on which packages are +available to include in your live image. Specify the codename, which +defaults to ${testing} for the ${testing} version of live-build. Any current +distribution carried in the archive may be specified by its codename +here. (See {Terms}#terms for more details.) The #{--distribution}# option +not only influences the source of packages within the archive, but also +instructs live-build to behave as needed to build each supported +distribution. For example, to build against the *{unstable}* release, sid, +specify: + +code{ + + $ lb config --distribution sid + +}code + +All'interno dell'archivio dei pacchetti, le aree sono le principali +divisioni dello stesso. In Debian queste sono #{main}#, #{contrib}# e +#{non-free}#; soltanto #{main}# contiene il software che è parte di Debian, +perciò questa è la predefinita. Possono essere specificati uno o più valori: + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Attraverso l'opzione #{--mode}# è disponibile un supporto sperimentale per +alcune derivate di Debian; per impostazione predefinita, questa opzione è +impostata su #{debian}# solo se si sta costruendo su un sistema Debian o +sconosciuto. Invocando #{lb config}# su una delle derivate supportate, verrà +creata un'immagine di quella derivata in modo predefinito. Se #{lb config}# +viene ad esempio eseguito in modalità #{ubuntu}#, saranno gestiti i nomi +della distribuzione e le aree di archivio per la derivata specificata e non +quelli di Debian. La modalità cambia anche il comportamento di live-build +per adattarlo alle derivate. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Mirror delle distribuzioni + +L'archivio Debian è replicato attraverso una vasta rete di mirror in tutto +il mondo cosicché chiunque in ogni nazione può selezionare il mirror più +vicino per una migliore velocità di scaricamento. Ciascuna delle opzioni +#{--mirror-*}# determina quale mirror della distribuzione è usato nei vari +stadi della compilazione. Ricordando dalle {Fasi della +creazione}#stages-of-the-build che la fase di *{avvio}* è quando il chroot è +inizialmente popolato da /{debootstrap}/ con un sistema minimale e quella di +*{chroot}* è quando viene creato il chroot usato per costruire il file +system del sistema live. Perciò per queste fasi vengono usati i +corrispondenti cambi di mirror, e in seguito, nella fase *{binaria}* vengono +usati i valori di #{--mirror-binary}# e #{--mirror-binary-security}# +sostituendo qualsiasi altro mirror usato nelle fasi iniziali. + +3~distribution-mirrors-build-time Mirror delle distribuzioni usati in fase +di compilazione + +To set the distribution mirrors used at build time to point at a local +mirror, it is sufficient to set #{--mirror-bootstrap}# and +#{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +Il mirror chroot, specificato da #{--mirror-chroot}#, è impostato al valore +di #{--mirror-bootstrap}# in modo predefinito. + +3~ Mirror delle distribuzioni usate durante l'esecuzione + +The #{--mirror-binary*}# options govern the distribution mirrors placed in +the binary image. These may be used to install additional packages while +running the live system. The defaults employ #{httpredir.debian.org}#, a +service that chooses a geographically close mirror based, among other +things, on the user's IP family and the availability of the mirrors. This is +a suitable choice when you cannot predict which mirror will be best for all +of your users. Or you may specify your own values as shown in the example +below. An image built from this configuration would only be suitable for +users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Repository addizionali + +Si possono aggiungere altri repository, ampliando così la scelta dei +pacchetti al di là di quelli disponibili nella distribuzione di +destinazione. Questi possono essere, per esempio, pacchetti di backport, +sperimentali o personalizzati. Per configurare repository aggiuntivi, creare +i file #{config/archives/vostro-repository.list.chroot}#, o +#{config/archives/vostro-repository.list.binary}#. Come per le opzioni +#{--mirror-*}#, queste controlleranno i repository usati nella fase +*{chroot}* quando si compila l'immagine, e nella fase *{binary}*, ad esempio +per usarli quando il sistema live è avviato. + +Per esempio, #{config/archives/live.list.chroot}# permette di installare +pacchetti dal repository snapshot debian-live al momento della creazione del +sistema live. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +Se si aggiunge la stessa riga in #{config/archives/live.list.binary}#, il +repository verrà aggiunto alla directory #{/etc/apt/sources.list.d/}# del +sistema live. + +Se questi file esistono saranno prelevati automaticamente. + +Bisogna inoltre inserire la chiave GPG usata per firmare il repository nei +file #{config/archives/vostro-repository.key.{binary,chroot}}#. + +Se si necessita di personalizzare il pinning di APT, le sezioni di APT +preferences possono essere inserite nei file +#{config/archives/mio-repository.pref.{binary,chroot}}# e verranno +automaticamente aggiunte nella directory #{/etc/apt/preferences.d/}# del +sistema live. + +2~choosing-packages-to-install Scegliere i pacchetti da installare + +Ci sono diversi modi per scegliere quali pacchetti live-build installerà +nell'immagine, coprendo una gamma di esigenze diverse. Si possono richiamare +i singoli pacchetti da un elenco, usare i metapacchetti o selezionarli +tramite il file control. E infine inserire i file dei pacchetti nell'albero +#{config/}#, che ben si adatta a provare pacchetti nuovi o sperimentali +prima che siano disponibili in un repository. + +3~package-lists Elenchi di pacchetti + +Gli elenchi di pacchetti sono un potente mezzo per esprimere quali pacchetti +devono essere installati. La sintassi gestisce sezioni condizionali rendendo +semplice la creazione di elenchi e adattarli per l'uso in molteplici +configurazioni. I nomi dei pacchetti possono inoltre essere inseriti +nell'elenco utilizzando script shell in fase di compilazione. + +*{Nota:}* quando si specifica un pacchetto che non esiste, il comportamento di live-build è determinato dalla scelta delle utilità di APT. Per ulteriori dettagli si veda {Scegliere apt o aptitude}#choosing-apt-or-aptitude. + +3~using-metapackages Usare metapacchetti + +Il metodo più semplice per popolare una lista di pacchetti è utilizzare un +metapacchetto task manutenuto dalla distribuzione. Ad esempio: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# +2.x. Unlike predefined lists, task metapackages are not specific to the Live +System project. Instead, they are maintained by specialist working groups +within the distribution and therefore reflect the consensus of each group +about which packages best serve the needs of the intended users. They also +cover a much broader range of use cases than the predefined lists they +replace. + +Tutti i metapacchetti task iniziano per #{task-}#, un modo per determinare +quali siano disponibili (sebbene possa contenere alcuni falsi positivi che +corrispondono al nome ma non sono metapacchetti) è di controllare il nome +del pacchetto con: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +In aggiunta a questi si trovano altri metapacchetti per vari scopi. Alcuni +sono dei sottoinsiemi dei pacchetti task generici, come #{gnome-core}#, +mentre altri sono parti individuali di un Debian Pure Blend, come il +metapacchetto #{education-*}#. Per elencarli tutti installare il pacchetto +#{debtags}# e usare il tag #{role::metapackage}# come segue: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Elenchi locali dei pacchetti + +Se si richiede l'elenco di metapacchetti, pacchetti individuali o una +combinazione di entrambi tutte le liste dei pacchetti locali vengono salvate +in #{config/package-lists/}#. Giacché è possibile usare più di una lista, +ciò si presta bene a progetti modulari. Si può ad esempio decidere di +dedicare un elenco ad un particolare desktop, un altro ad un insieme di +pacchetti correlati utilizzabili con desktop differenti. Questo permette di +sperimentare diverse combinazioni di insiemi di pacchetti con il minimo +sforzo condividendo gli elenchi tra progetti live differenti. + +Per essere processati, gli elenchi dei pacchetti che si trovano in questa +directory devono avere un suffisso #{.list}# e un suffisso #{.chroot}# o +#{.binary}# aggiuntivo per indicare per quale fase sia l'elenco. + +*{Nota:}* se non si specifica il suffisso l'elenco sarà usato per entrambe le fasi. Normalmente è preferibile specificare #{.list.chroot}# in modo che i pacchetti vengono installati solo nel filesystem live evitando di avere una copia extra del #{.deb}# sul dispositivo. + +3~ Elenchi locali di pacchetti binari + +Per creare un elenco di binari inserire un file con suffisso +#{.list.binary}# in #{config/package-lists/}#; questi pacchetti non sono +installati nel filesystem ma inclusi sul dispositivo live sotto +#{pool/}#. Solitamente questo elenco si usa con una delle varianti non-live +dell'installatore; come detto sopra, se si vuole che questo sia identico +all'elenco della fase chroot, usare semplicemente il suffisso #{.list}#. + +3~generated-package-lists Elenchi di pacchetti generati + +Talvolta succede che il modo migliore per ottenere un elenco è di generarlo +con uno script. Ogni riga che inizia con un punto esclamativo indica un +comando da eseguire nel chroot quando viene creata l'immagine. Ad esempio si +potrebbe includere la riga #{! grep-aptavail -n -sPackage -FPriority +standard | sort}# in una lista di pacchetti per produrne una contenente i +pacchetti con #{Priority: standard}# disponibili. + +Infatti selezionare i pacchetti con il comando #{grep-aptavail}# (presente +nel pacchetto #{dctrl-tools}#) è talmente utile che #{live-build}# fornisce +uno script #{Packages}# per comodità; accetta due argomenti: #{field}# e +#{pattern}#. Per cui si può creare un elenco con il seguente contenuto: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Usare condizioni all'interno degli elenchi di pacchetti + +Ognuna delle variabili di configurazione di live-build situate in +#{config/*}# (senza il prefisso #{LB_}#) possono essere utilizzate per +istruzioni condizionali nell'elenco dei pacchetti. In genere questo +significa qualsiasi opzione di #{lb config}# in maiuscolo e con trattini +cambiati in trattini bassi; ma in pratica è la sola ad influenzare la +selezione dei pacchetti che abbia senso, come #{DISTRIBUTION}#, +#{ARCHITECTURES}# o #{ARCHIVE_AREAS}#. + +Per esempio, per installare #{ia32-libs}# se è specificata #{--architectures +amd64}#: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +Si può provare per ognuna di una serie di valori, ad esempio per installare +/{memtest86+}/ specificando sia #{--architectures i386}# sia +#{--architectures amd64}#: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +È possibile provare altre variabili che contengano più di un valore, ad +esempio per installare /{vrms}/ specificando sia da #{contrib}# sia da +#{non-free}# tramite #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +Le condizioni nidificate non sono supportate. + +% FIXME: + +3~ Removing packages at install time + +You can list packages in files with #{.list.chroot_live}# and +#{.list.chroot_install}# suffixes inside the #{config/package-lists}# +directory. If both a live and an install list exist, the packages in the +#{.list.chroot_live}# list are removed with a hook after the installation +(if the user uses the installer). The packages in the +#{.list.chroot_install}# list are present both in the live system and in the +installed system. This is a special tweak for the installer and may be +useful if you have #{--debian-installer live}# set in your config, and wish +to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Task per desktop e lingua + +I task per i desktop e la lingua sono un caso particolare che necessita di +ulteriori pianificazioni e configurazioni e in questo senso le immagini live +sono diverse da quelle dell'Installatore Debian. Nell'Installatore Debian, +se il supporto è stato preparato per un particolare ambiente desktop, il +corrispondente task verrà automaticamente installato. Perciò ci sono task +#{gnome-desktop}#, #{kde-desktop}#, #{lxde-desktop}# e #{xfce-desktop}# +interni, nessuno dei quali è offerto nel menu di #{tasksel}#. Allo stesso +modo, non c'è nessuna voce nel menu per i task delle lingue, ma la scelta +della lingua dell'utente durante l'installazione influenza la selezione dei +corrispondenti task della lingua. + +Sviluppando un'immagine live per desktop, questa si avvia direttamente su +un'area di lavoro, le scelte del desktop e della lingua predefinita sono +state fatte al momento della compilazione e non al volo come nel caso +dell'installatore Debian. Questo non per dire che un'immagine live non possa +essere creata con un supporto per desktop o lingue multipli per offrire +all'utente una scelta, ma che non è il comportamento predefinito nella +creazione di una live. + +Poiché automaticamente non viene fatta alcuna preparazione sui task della +lingua, i quali includono cose come caratteri specifici per la lingua e +pacchetti per i metodi di input, se li si vogliono, vanno specificati nella +configurazione. Per esempio, un'immagine del desktop GNOME contenente il +supporto per il tedesco può includere questi metapacchetti task: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Tipi e versioni del kernel + +A seconda dell'architettura, nell'immagine verranno inclusi uno o più tipi +di kernel in modo predefinito. È possibile scegliere tipi differenti tramite +l'opzione #{--linux-flavours}#, ognuno ha come suffisso #{linux-image}# che +costituisce il nome del metapaccchetto che a sua volta dipende dall'esatto +pacchetto del kernel da inserire nell'immagine. + +Thus by default, an #{amd64}# architecture image will include the +#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture +image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured +archives, you can specify a different kernel package name stub with the +#{--linux-packages}# option. For example, supposing you are building an +#{amd64}# architecture image and add the experimental archive for testing +purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# +kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Kernel personalizzati + +Si può compilare e includere i propri kernel personalizzati a patto che +siano integrati nel sistema di gestione dei pacchetti di Debian. Il sistema +live-build non supporta i kernel né crea pacchetti #{.deb}#. + +La maniera corretta e raccommandata per collocare i propri pacchetti è di +seguire le istruzioni nel #{kernel-handbook}#. Ricordarsi di modificare i +suffissi per ABI e tipologia in modo appropriato quindi includere una +compilazione completa del pacchetto #{linux}# e del corrispondente +#{linux-latest}# nel reposistory. + +Se si opta per creare i pacchetti del kernel senza i metapacchetti +corrispondenti, bisogna specificare un suffisso #{--linux-packages}# +appropriato come discusso in {Tipi e versioni del +kernel}#kernel-flavour-and-version. Come spiegato in {Installare pacchetti +modificati o di terze parti}#installing-modified-or-third-party-packages, è +meglio includere i propri pacchetti del kernel nel proprio repository, +sebbene funzionino anche le alternative discusse in tale sezione. + +Fornire suggerimenti sul come personalizzare il proprio kernel va oltre lo +scopo di questa documentazione, tuttavia è necessario assicurarsi che la +configurazione soddisfi almeno i seguenti requisiti minimi: + +_* Utilizzare un ramdisk iniziale; + +_* includere il modulo del filesystem union (solitamente #{aufs}#); + +_* includere qualsiasi altro modulo del filesystem necessario alla +configurazione (solitamente #{squashfs}#). + +2~installing-modified-or-third-party-packages Installare pacchetti +modificati o di terze parti + +While it is against the philosophy of a live system, it may sometimes be +necessary to build a live system with modified versions of packages that are +in the Debian repository. This may be to modify or support additional +features, languages and branding, or even to remove elements of existing +packages that are undesirable. Similarly, "third-party" packages may be used +to add bespoke and/or proprietary functionality. + +Questa sezione non tratta la compilazione e il mantenimento di pacchetti +modificati. Può comunque essere interessante leggere "How to fork privately" +di Joachim Breitner: +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +La creazione di pacchetti su misura è esposta nella "Guida per il nuovo +Maintainer" all'indirizzo https://www.debian.org/doc/maint-guide/ e altrove. + +Ci sono due modi per installare pacchetti personalizzati: + +_* #{packages.chroot}# + +_* utilizzare repository APT personalizzati + +Usando #{packages.chroot}# è più semplice da ottenere e utile per una +personalizzazione "una tantum" ma ha una serie di svantaggi, mentre un +repository APT personalizzato è più laborioso da configurare. + +3~ Utilizzare #{packages.chroot}# per installare pacchetti personalizzati + +Per installare un pacchetto personalizzato copiarlo nella directory +#{config/packages.chroot/}#; i pacchetti al suo interno verranno installati +automaticamente durante la creazione del sistema live, non è necessario +specificarli altrove. + +I pacchetti *{devono}* essere nominati nel modo prescritto, un metodo +semplice per farlo è usare #{dpkg-name}#. + +L'utilizzo di #{packages.chroot}# per l'installazione di pacchetti +personalizzati presenta degli svantaggi: + +_* non è possibile usare secure APT, + +_* è necessario installare i pacchetti adeguati nella directory +#{config/packages.chroot/}#, + +_* It does not lend itself to storing live system configurations in revision +control. + +3~ Utilizzare un repository APT per installare pacchetti personalizzati + +A differenza di #{packages.chroot}#, quando si usa un repository APT +personalizzato è necessario assicurarsi di specificare altrove i +pacchetti. Per i dettagli si veda {Scegliere i pacchetti da +installare}#choosing-packages-to-install. + +Sebbene creare un repository APT possa sembrare uno sforzo inutile, +l'infrastruttura può facilmente essere riutilizzata in un secondo momento +per offrire aggiornamenti dei pacchetti modificati. + +3~ Pacchetti personalizzati e APT + +live-build utilizza APT per installare tutti i pacchetti nel sistema live in +modo da ereditare i comportamenti di questo programma. Un esempio rilevante +è che (considerando una configurazione predefinita) dato un pacchetto +disponibile in due repository differenti con numeri di versione diversi, APT +sceglie di installare quello con il numero di versione più alto. + +A causa di questo si può voler incrementare il numero della versione nei +file #{debian/changelog}# dei pacchetti personalizzati per accertare che la +propria versione avrà la precedenza sui repository Debian ufficiali. È anche +ottenibile modificando le preferenze del APT pinning del sistema live, si +veda {APT pinning}#apt-pinning per maggiori informazioni. + +2~ Configurare APT in fase di compilazione + +APT è configurabile tramite una serie di opzioni applicate solo in fase di +costruzione (la configurazione di APT utilizzata nel sistema live in +esecuzione può essere configurata nel solito modo, ovvero includendo le +impostazioni appropriate attraverso #{config/includes.chroot/}#). Per un +elenco completo, cercare nel manuale di #{lb_config}# le opzioni che +iniziano con #{apt}#. + +3~choosing-apt-or-aptitude Scegliere apt o aptitude + +Per installare pacchetti in fase di compilazione si può optare sia per +/{apt}/ sia per /{aptitude}/, l'argomento #{--apt}# di #{lb config}# +determina quale usare. Sceglie il metodo implementando il comportamento +preferito per l'installazione dei pacchetti, la notevole differenza è come +vengono gestiti quelli mancanti. + +_* #{apt}#: se viene specificato un pacchetto mancante, l'installazione avrà +esito negativo; questo è l'impostazine predefinita. + +_* #{aptitude}#: se viene specificato un pacchetto mancante, l'installazione +avrà successo. + +3~ Utilizzare un proxy con APT + +Una configurazione di APT spesso richiesta è di amministrare la creazione di +un'immagine dietro un proxy, lo si può specificare con le opzioni +#{--apt-ftp-proxy}# o #{--apt-http-proxy}# secondo necessità: + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Modificare APT per risparmiare spazio + +Si può aver bisogno di risparmiare dello spazio sul supporto dell'immagine, +in tal caso una o entrambe delle seguenti opzioni possono essere +d'interesse. + +È possibile non includere gli indici di APT con: + +code{ + + $ lb config --apt-indices false + +}code + +Questo non influenzerà le voci in #{/etc/apt/sources.list}#, determina solo +se /#{var/lib/apt}# contiene o meno i file degli indici. Il compromesso è +che APT necessita di quegli indici per operar enel sistema live, perciò +prima di eseguire #{apt-cache search}# o #{apt-get install}#, per esempio, +l'utente deve usare prima #{apt-get update}# per crearli. + +In caso si trovi che l'installazione dei pacchetti raccomandati appesantisca +troppo l'immagine, a patto si è preparati ad affrontare le conseguenze +discusse prima, si può disabilitare l'opzione predefinita di APT con: + +code{ + + $ lb config --apt-recommends false + +}code + +La conseguenza più importante di disattivare i raccomandati è che +#{live-boot}# e #{live-config}# raccomandano a loro volta alcuni pacchetti +che forniscono funzionalità importanti utilizzate da molte configurazioni, +come #{user-setup}# che #{live-config}# raccomanda ed è usato per creare +l'utente live. Salvo eccezioni ci sarà bisogno di riaggiungere all'elenco +almeno alcuni di questi o l'immagine non funzionerà come ci si +aspetta. Controllare i raccomandati per ognuno dei pacchetti #{live-*}# +inclusi nella compilazione, se non si è certi di poterli omettere +aggiungerli nuovamente agli elenchi. + +La conseguenza generica è che se non si installano i raccomandati per un +certo pacchetto, ovvero "pacchetti che si trovano assieme a questo eccetto +in installazioni non usuali" (Debian Policy Manual, paragrafo 7.2), saranno +omessi alcuni di quelli realmente necessari. Si suggerisce pertanto di +verificare la differenza ottenuta nel proprio elenco di pacchetti +disabilitando i raccomandati (vedere il file #{binary.packages}# generato da +#{lb build}#) e includere nuovamente in esso quelli omessi che si desiderano +installare. In alternativa, se si desidera tenere un modesto numero di +raccomandati, li si lasci abilitati e si assegni ad APT un pin di priorità +negativo sui pacchetti selezionati affinché non vengano installati, come +spiegato in {APT pinning}#apt-pinning. + +3~ Passare opzioni ad apt o aptitude + +Se non esiste un'opzione di #{lb config}# per modificare il comportamento di +APT come si desidera, utilizzare #{--apt-options}# o #{--aptitude-options}# +per passare qualsiasi argomento tramite lo strumento APT scelto. Per i +dettagli consultare le pagine di manuale di #{apt}# e #{aptitude}#. Notare +che entrambe le opzioni hanno valori predefiniti che servirà mantenere in +aggiunta a qualsiasi altra fornita. Per cui supponendo di aver incluso +qualcosa da #{snapshot.debian.org}# per fare dei test e volendo specificare +#{Acquire::Check-Valid-Until=false}# per soddisfare APT con il vecchio file +#{Release}#, si procederà come nell'esempio riportato di seguito, appendendo +la nuova opzione al valore predefinito #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Per apprendere a pieno queste opzioni e sapere quando usarle consultare i +manuali. Questo è solo un esempio e non va interpretato come il modo per +configurare la propria immagine, non sarebbe appropriato per il rilascio +finale. + +Per configurazioni di APT più complesse che comportano l'uso di opzioni in +#{apt.conf}# si può voler creare invece il file +#{config/apt/apt.conf}#. Vedere anche le altre opzioni #{apt-*}# per alcune +comode scorciatoie di operazioni di uso frequente. + +3~apt-pinning APT pinning + +Si prega di leggere prima il manuale di #{apt_preferences(5)}#. Il pinning +può essere configurato sia in fase di costruzione sia di esecuzione; per la +prima creare #{config/archives/*.pref}#, #{config/archives/*.pref.chroot}#, +e #{config/apt/preferences}# mentre per l'ultima creare +#{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live +packages that end up in the binary image to be installed from sid at build +time. You need to add sid to your APT sources and pin the live packages from +it higher, but all other packages from it lower, than the default +priority. Thus, only the packages you want are installed from sid at build +time and all others are taken from the target system distribution, +${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Un valore negativo della priorità evita che un pacchetto venga installato, +come nel caso in cui non se ne voglia uno raccomandato da un +altro. Supponiamo di costruire un'immagine di LXDE utilizzando l'opzione +#{task-lxde-desktop}# in #{config/package-lists/desktop.list.chroot} ma non +si desidera che all'utente venga richiesto di salvare la password del wifi +nel portachiavi. Questo metapacchetto dipende da /{lxde-core}/ che +raccomanda /{gksu}/ e che a sua volta raccomanda /{gnome-keyring}/, in +questo caso si vorrà omettere il pacchetto /{gnome-keyring}/ aggiungendo a +#{config/apt/preferences}# la seguente istruzione: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-runtime.ssi new file mode 100644 index 0000000..4d65a84 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_customization-runtime.ssi @@ -0,0 +1,452 @@ +:B~ Personalizzare i comportamenti durante l'esecuzione + +1~customizing-run-time-behaviours Personalizzare i comportamenti durante +l'esecuzione + +Tutte le configurazioni durante l'esecuzione sono eseguite da +live-config. Vengono qui presentate alcune delle opzioni di live-config più +comuni alle quali gli utenti sono interessati; una lista completa può essere +trovata nel suo manuale. + +2~ Personalizzare l'utente live + +Un'importante considerazione è che l'utente live viene creato all'avvio da +live-boot e non da live-build durante la compilazione. Questo non solo +influenza dove viene introdotto il materiale relativo all'utente nella +creazione, come discusso in {Live/chroot include +locali}#live-chroot-local-includes, ma anche ogni gruppo e permesso +associato all'utente live. + +È possibile specificare gruppi aggiuntivi ai quali l'utente live apparterrà +utilizzando una delle possibilità di configurazione di live-config. Ad +esempio, per aggiungere l'utente al gruppo #{fuse}#, è possibile sia +inserire in #{config/includes.chroot/etc/live/config/user-setup.conf}# +quanto segue: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +o utilizzare +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +come parametro di boot. + +È inoltre possibile modificare facilmente il nome utente "user" e la +password "live" predefiniti. + +Per cambiare il nome utente specificare quanto segue nella configurazione: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +Un modo per cambiare la password è tramite un hook come descritto in {Hook +in fase di avvio}#boot-time-hooks. Si può usare l'hook "passwd" da +#{/usr/share/doc/live-config/examples/hooks}#, anteponendolo di conseguenza +(ad esempio, 2000-passwd) e aggiungerlo al file +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Personalizzare la localizzazione e la +lingua + +Quando il sistema live si avvia, la lingua è inserita in due fasi: + +_* generazione della localizzazione + +impostare la configurazione della tastiera + +Quando si crea un sistema live la localizzazione predefinita è +#{locales=en_US.UTF-8}#. Per definire quale generare, si usi il parametro +#{locales}# nell'opzione #{--bootappend-live}# di #{lb config}#: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Possono essere specificate più lingue separate da una virgola. + +Questo parametro, così come quelli della tastiera indicati più avanti, può +essere usato anche dalla riga di comando del kernel specificando una lingua +con #{language_country}# (nel qual caso verrà usata la codifica predefinita) +o l'intera stringa #{language_country.encoding}#. In +#{/usr/share/i18n/SUPPORTED}# è possibile trovare un elenco delle lingue +supportate e la codifica per ognuna di esse. + +Sia la configurazione della tastiera in console sia di X sono eseguite da +#{live-config}# con il pacchetto #{console-setup}#. Per fare ciò usare i +parametri #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# +e #{keyboard-model}# tramite l'opzione #{--bootappend-live}#. Le opzioni +valide si trovano in #{/usr/share/X11/xkb/rules/base.lst}#. Per ottenere i +layout e le varianti di una data lingua, provare a cercare il loro nome +inglese o il paese in cui è usata, esempio: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Notare che ogni variante mostra nella descrizione il layout alla quale viene +applicata. + +Spesso c'è bisogno di configurare solo il layout. Ad esempio per ottenere i +file di localizzazione per il layout di tastiera tedesco e svizzero-tedesco +in X: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +Tuttavia per casi molto particolari si vorrà includere altri parametri. Ad +esempio per configurare un sistema in francese con un layout Dvorak +(chiamato Bepo) su una tastiera USB TypeMatrix EZ-Reach 2030: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Per ogni opzione #{keyboard-*}# si possono specificare più valori separati +da una virgola, con l'eccezione di #{keyboard-model}# che ne accetta uno +solo. Consultare la pagina di manuale di #{keyboard(5)}# per dettagli ed +esempi delle variabili #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# e +#{XKBOPTIONS}#. Se vengono forniti più valori per #{keyboard-variants}#, +questi verranno combinati uno ad uno con quelli di #{keyboard-layouts}# +(vedere l'opzione #{-variant}# in #{setxkbmap(1)}# ). Sono permessi valori +vuoti, ad esempio per definire due layout, US QWERTY come predefinito e US +Dvorak, usare: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistenza + +Uno dei paradigmi di un cd live è un sistema preinstallato eseguito da un +supporto in sola lettura, come un cdrom, dove le modifiche non sopravvivono +ai riavvii dell'hardware della macchina ospitante. + +Un sistema live è una generalizzazione di questo paradigma e di conseguenza +oltre ai CD gestisce altri supporti; ma comunque, nel suo comportamento +predefinito, deve essere considerato in sola lettura e tutte i cambiamenti +fatti durante l'esecuzione del sistema verranno persi allo spegnimento. + +Persistenza è il nome comune per differenti tipi di soluzioni per salvare +alcune o tutte queste modifiche con i riavii. Per capire come funziona +potrebbe essere utile sapere che sebbene il sistema venga avviato ed +eseguito da un dispositivo in sola lettura, le modifiche a file e directory +vengono scritte su uno scrivibile, tipicamente un ram disk (tmpfs) e i dati +sui ram disk non sopravvivono ai riavvii. + +I dati immagazzinati su questo ramdisk andrebbero salvati un supporto +scrivibile persistente come un supporto di memorizzazione locale, una +condivisione di rete o anche una sessione di un CD/DVD riscrivibile +multisessione. Tutti questi supporti sono gestiti in modi differenti e tutti +tranne l'ultimo richiedono un parametro d'avvio speciale da specificare +all'avvio: #{persistence}#. + +Se il parametro di boot #{persistence}# è impostato (e non lo è +#{nopersistence}#), i supporti di memorizzazione locali (hard disk, +dispositivi USB) saranno rilevati come volumi persistenti durante l'avvio. È +possibile selezionare quali tipi utilizzare specificando certi parametri di +avvio descritti nella manpage di live-boot(7). Un volume persistente è uno +dei seguenti: + +_* una partizione, identificata dal suo nome GPT (GUID Partition Table). + +_* un filesystem, identificato dalla sua label. + +_* un file immagine situato nella directory radice di un qualsiasi +filesystem leggibile (anche una partizione NTFS di un sistema estraneo), +identificato dal nome del file. + +La label del volume per le stratificazioni deve essere #{persistence}# ma +verrà ignorata a meno che non sia presente nella directory radice un file +chiamato #{persistence.conf}# che viene usato per personalizzare la +persistenza del volume, in altre parole, specificare le directory che si +vogliono salvare dopo un riavvio. Per maggiori dettagli vedere {Il file +persistence.conf}#persistence-conf. + +Ecco alcuni esempi per preparare un volume da utilizzare per la +persistenza. Può ad esempio essere una partizione ext4 su un hard disk o una +penna USB creata con: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +Vedere anche {Usare lo spazio rimanente su una penna +USB}#using-usb-extra-space. + +Se si possiede già una partizione sul dispositivo basta solo cambiare +l'etichetta con una delle seguenti: + +code{ + + # tune2fs -L persistence /dev/sdb1 # per filesystem ext2,3,4 + +}code + +Un esempio di come creare un file immagine ext4 da utilizzare per la +persistenza: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Una volta che il file immagine è stato creato, ad esempio per rendere +#{/usr}# persistente salvando solo le modifiche fatte a quella directory e +non tutto il contenuto di #{/usr}#, si può usare l'opzione "union". Se +l'immagine è situata nella propria home copiarla nella radice del filesystem +sul disco e montarla in #{/mnt}# come segue: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Creare quindi il file #{persistence.conf}# aggiungendovi il contenuto e +smontare il file immagine. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Ora riavviare il dispositivo live con il parametro d'avvio "persistence". + +3~persistence-conf Il file persistence.conf + +Un volume con la label #{persistence}# deve essere configurato mediante il +file #{persistence.conf}# per creare directory persistenti arbitrarie. Tale +file, situato nella directory radice del filesystem del volume, controlla +quali rendere persistenti e in che modo. + +Nella manpage di persistence.conf(5) è descritto dettagliatamente come è +configurato il mount degli strati personalizzati, ma un semplice esempio +dovrebbe essere sufficiente per la maggior parte degli usi. Supponendo di +voler creare la directory home e quella della cache di APT in modo +persistente in un filesystem ext4 sulla partizione /dev/sdb1: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Quindi riavviare. Durante il primo avvio il contenuto di #{/home}# e +#{/var/cache/apt}# saranno copiati nel volume persistente e da allora tutte +le modifiche a queste directory risiederanno in modo persistente sul +volume. C'è da considerare che tutti i path elencati nel file +#{persistence.conf}# non possono contenere spazi o i caratteri speciali +#{.}# e #{..}#, inoltre né #{/lib}#, #{/lib/live}# (o una delle sue +sottodirectory) né #{/}# può essere resa persistente tramite i mount +personalizzati. Come workaround a questa limitazione è possibile aggiungere +#{/ union}# al file #{persistence.conf}# file per ottenere la persistenza +completa. + +3~ Utilizzare più di un'archiviazione persistente + +Ci sono tre metodi differenti di utilizzare persistenze multiple per +differenti casi d'uso. Ad esempio l'utilizzo di svariati volumi +contemporaneamente o selezionandone uno solo per scopi molto specifici. + +Possono essere utilizzati svariati volumi di stratificazione personalizzati +(con i rispettivi file #{persistence.conf}#) allo stesso tempo ma se questi +creano la stessa directory persistente, ne verrà usata solo una. Se due +directory montate sono "nidificate" (una è la sottodirectory dell'altra), la +superiore sarà montata per prima, per cui nessuna operazione di mount verrà +sovrastata dall'altra. I mount nidificati personalizzati sono problematici +se sono elencati nello stesso file #{persistence.conf}#. Se si ha davvero la +necessità (in genere non si dovrebbe averla), consultare la manpage di +persistence.conf(5) per sapere come gestire questo caso. + +One possible use case: If you wish to store the user data i.e. #{/home}# and +the superuser data i.e. #{/root}# in different partitions, create two +partitions with the #{persistence}# label and add a #{persistence.conf}# +file in each one like this, #{# echo "/home" > persistence.conf}# for the +first partition that will save the user's files and #{# echo "/root" > +persistence.conf}# for the second partition which will store the superuser's +files. Finally, use the #{persistence}# boot parameter. + +Se un utente avesse bisogno di spazi di archiviazione multipli dello stesso +tipo per posizioni differenti o per test, come #{privato}# e #{lavoro}#, il +parametro d'avvio #{persistence-label}# usato in congiunzione con +#{persistent}# permetterà supporti persistenti multipli ma univoci. Un +esempio potrebbe essere un utente che vuole usare una partizione etichettata +come #{privato}# per dati personali come i preferiti del browser o di altro +tipo, questi userà i parametri d'avvio #{persistence}# +#{persistence-label=privato}#. E per archiviare dati inerenti il lavoro, +come documenti, ricerche e altro, verranno usati i parametri d'avvio +#{persistence}# #{persistence-label=lavoro}#. + +È importante ricordare che ognuno di questi volumi, #{privato}# e +#{lavoro}#, necessitano anche di un file #{persistence.conf}# nella propria +radice. Il manuale di live-boot contiene altre informazioni su come +utilizzare queste etichette con nomi usati in versioni precedenti. + +3~ Using persistence with encryption + +Using the persistence feature means that some sensible data might get +exposed to risk. Especially if the persistent data is stored on a portable +device such as a usb stick or an external hard drive. That is when +encryption comes in handy. Even if the entire procedure might seem +complicated because of the number of steps to be taken, it is really easy to +handle encrypted partitions with live-boot. In order to use *{luks}*, which +is the supported encryption type, you need to install /{cryptsetup}/ both on +the machine you are creating the encrypted partition with and also in the +live system you are going to use the encrypted persistent partition with. + +To install /{cryptsetup}/ on your machine: + +code{ + + # apt-get install cryptsetup + +}code + +To install /{cryptsetup}/ in your live system, add it to your package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Once you have your live system with /{cryptsetup}/, you basically only need +to create a new partition, encrypt it and boot with the #{persistence}# and +#{persistence-encryption=luks}# parameters. We could have already +anticipated this step and added the boot parameters following the usual +procedure: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Let's go into the details for all of those who are not familiar with +encryption. In the following example we are going to use a partition on a +usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need +to determine which partition is the one you are going to use in your +specific case. + +The first step is plugging in your usb stick and determine which device it +is. The recommended method of listing devices in live-manual is using #{ls +-l /dev/disk/by-id}#. After that, create a new partition and then, encrypt +it with a passphrase as follows: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Then open the luks partition in the virtual device mapper. Use any name you +like. We use *{live}* here as an example: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +The next step is filling the device with zeros before creating the +filesystem: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Now, we are ready to create the filesystem. Notice that we are adding the +label #{persistence}# so that the device is mounted as persistence store at +boot time. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +To continue with our setup, we need to mount the device, for example in +#{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +And create the #{persistence.conf}# file in the root of the partition. This +is, as explained before, strictly necessary. See {The persistence.conf +file}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Then unmount the mount point: + +code{ + + # umount /mnt + +}code + +And optionally, although it might be a good way of securing the data we have +just added to the partition, we can close the device: + +code{ + + # cryptsetup luksClose live + +}code + +Let's summarize the process. So far, we have created an encryption capable +live system, which can be copied to a usb stick as explained in {Copying an +ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also +created an encrypted partition, which can be located in the same usb stick +to carry it around and we have configured the encrypted partition to be used +as persistence store. So now, we only need to boot the live system. At boot +time, live-boot will prompt us for the passphrase and will mount the +encrypted partition to be used for persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_installation.ssi new file mode 100644 index 0000000..7c84b02 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_installation.ssi @@ -0,0 +1,177 @@ +:B~ Installazione + +1~installation Installazione + +2~requirements Requisiti + +Building live system images has very few system requirements: + +_* Accesso come utente root + +_* Una versione aggiornata di live-build + +_* Una shell POSIX-compliant, come /{bash}/ o /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6 o successivi + +Si noti che usare Debian o una distribuzione derivata Debian non è richiesto +- live-build funzionerà sostanzialmente su qualsiasi distribuzione che +soddisfi i requisiti di cui sopra. + +2~installing-live-build Installare live-build + +Si può installare live-build in diversi modi: + +_* Dal repository Debian + +_* Da sorgenti + +_* Da istantanee + +Se si sta usando Debian, il metodo raccomandato è di installare live-build +attraverso il repository Debian. + +3~ Dal repository Debian + +Installare live-build come qualsiasi altro pacchetto: + +code{ + + # apt-get install live-build + +}code + +3~ Da sorgenti + +live-build è sviluppato usando il sistema di controllo versione Git. Sui +sistemi basati su Debian è fornito dal pacchetto /{git}/. Per scaricare il +codice aggiornato, eseguire: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +È possibile costruirsi ed installarsi il proprio pacchetto Debian eseguendo: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Si installino ora i file #{.deb}# appena generati ai quali si è interessati, +ad esempio: + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +Si può anche installare live-build direttamente sul proprio sistema +eseguendo: + +code{ + + # make install + +}code + +e disinstallarlo con: + +code{ + + # make uninstall + +}code + +3~ Da "istantanee" + +Se non si desidera generare o installare live-build da sorgenti, è possibile +usare le istantanee. Sono costruite automaticamente dall'ultima versione +presente su Git e disponibili su http://live-systems.org/debian/. + +2~ Installare live-boot e live-config + +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. + +3~ Dal repository Debian + +Sia live-boot che live-config sono disponibili dai repository Debian come +per l'{installazione di live-build}#installing-live-build. + +3~ Da sorgenti + +Per utilizzare i sorgenti più recenti da Git si può seguire il procedimento +seguente. Assicurarsi di conoscere i termini menzionati nel +{Glossario}#terms. + +_* Scaricare i sorgenti di live-boot e live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consultare la pagine man di live-boot e live-config per i dettagli sulla +personalizzazione se questa è il motivo per compilare questi pacchetti dai +sorgenti. + +_* Costruire un .deb di live-boot e live-config + +You must build either on your target distribution or in a chroot containing +your target platform: this means if your target is ${testing} then you +should build against ${testing}. + +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to +build live-boot for a target distribution that differs from your build +system. For example, for ${testing} live images, build live-boot in a +${testing} chroot. If your target distribution happens to match your build +system distribution, you may build directly on the build system using +#{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Usare il .deb di live-boot generato + +As live-boot and live-config are installed by live-build system, installing +the packages in the host system is not sufficient: you should treat the +generated .deb files like any other custom packages. Since your purpose for +building from source is likely to test new things over the short term before +the official release, follow {Installing modified or third-party +packages}#installing-modified-or-third-party-packages to temporarily include +the relevant files in your configuration. In particular, notice that both +packages are divided into a generic part, a documentation part and one or +more back-ends. Include the generic part, only one back-end matching your +configuration, and optionally the documentation. Assuming you are building a +live image in the current directory and have generated all .deb files for a +single version of both packages in the directory above, these bash commands +would copy all of the relevant packages including default back-ends: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ Da "istantanee" + +You can let live-build automatically use the latest snapshots of live-boot +and live-config by configuring the package repository on live-systems.org as +a third-party repository in your live-build configuration directory. diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_managing_a_configuration.ssi new file mode 100644 index 0000000..fbe3d1a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_managing_a_configuration.ssi @@ -0,0 +1,137 @@ +:B~ Gestire una configurazione + +1~managing-a-configuration Gestire una configurazione + +Questo capitolo spiega come gestire una configurazione per una live sin +dalla creazione iniziale, attraverso le successive revisioni e rilasci sia +del software live-build che della stessa immagine. + +2~ Gestire i cambiamenti di configurazione + +Le configurazioni live sono di rado perfette al primo tentativo. Può andar +bene passare le opzioni di #{lb config}# a riga di comando per eseguire una +compilazione ma è tipico rivedere queste opzioni e compilare finché non si è +soddisfatti. Per gestire le modifiche c'è bisogno di script automatici che +assicurano che la propria configurazione sia coerente. + +3~ Perché utilizzare gli script automatici? Cosa fanno? + +The #{lb config}# command stores the options you pass to it in #{config/*}# +files along with many other options set to default values. If you run #{lb +config}# again, it will not reset any option that was defaulted based on +your initial options. So, for example, if you run #{lb config}# again with a +new value for #{--binary-images}#, any dependent options that were defaulted +for the old image type may no longer work with the new ones. Nor are these +files intended to be read or edited. They store values for over a hundred +options, so nobody, let alone yourself, will be able to see in these which +options you actually specified. And finally, if you run #{lb config}#, then +upgrade live-build and it happens to rename an option, #{config/*}# would +still contain variables named after the old option that are no longer valid. + +Per queste ragioni gli script nella directory #{auto/*}# faciliteranno il +lavoro; sono semplici wrapper ai comandi #{lb config}#, #{lb build}# e #{lb +clean}# designati per aiutare a gestire la configurazione. Gli script in +#{auto/config}# memorizzano i comandi di #{lb config}# con le opzioni +desiderate, quelli in #{auto/clean}# rimuovono i file contenenti i valori +delle variabili di configurazione, mentre gli script in #{auto/build}# +tengono un #{build.log}# di ogni compilazione. Ognuno di questi script viene +eseguito automaticamente ogni qualvolta si esegue il comando #{lb}# +corrispondente; utilizzandoli la vostra configurazione sarà più semplice da +leggere e verrà mantenuta coerente da una revisione all'altra. Inoltre sarà +molto più facile identificare e sistemare le opzioni che necessitano di +modifiche quando si aggiorna live-build dopo aver letto la documentazione +aggiornata. + +3~ Esempi d'uso di script automatici + +Per comodità live-build è fornito di esempi di script automatici da copiare +e modificare. Inizializzare una nuova configurazione predefinita quindi +copiare gli esempi in essa: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Modificare #{auto/config}# aggiungendo qualsiasi opzione vi serva, esempio: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Ogni volta che verrà usato #{lb config}#, #{auto/config}# ripristinerà la +configurazione in base a queste opzioni; quando si vogliono apportare +modifiche basterà modificare le opzioni in questo file invece di passarle a +#{lb config}#. Utilizzando #{lb clean}#, #{auto/clean}# pulirà i file in +#{config/*}# insieme a qualsiasi altro creato dalla compilazione. Infine, +quando si usa #{lb build}#, verrà scritto da #{auto/build}# un file di log +della compilazione in #{build.log}#. + +*{Nota:}* il parametro speciale #{noauto}# viene qui usato per impedire un'ulteriore chiamata di #{auto/config}#, impedendo quindi infinite chiamate ricorsive; assicurarsi di non rimuoverlo facendo modifiche. Quando si dividono comandi lunghi di #{lb config}# su più righe per agevolarne la leggibilità, non dimenticare il backslash (\) alla fine di ogni riga che continua sulla successiva, come mostrato poc'anzi nell'esempio di script. + +2~clone-configuration-via-git Clonare una configurazione pubblicata tramite +Git. + +Use the #{lb config --config}# option to clone a Git repository that +contains a live system configuration. If you would like to base your +configuration on one maintained by the ${project}, look at +http://live-systems.org/gitweb/ for the repository named #{live-images}# in +the category #{Packages}#. This repository contains the configurations for +the live systems {prebuilt images}#downloading-prebuilt-images. + +For example, to build a standard image, use the #{live-images}# repository +as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Modificare #{auto/config}# e qualsiasi altro file presente in #{config}# +necessario alle proprie esigenze. Ad esempio, le immagini non-free +precompilate non ufficiali sono create semplicemente aggiungendo +#{--archive-areas "main contrib non-free"}#. + +È possibile definire una scorciatoia nella configurazione di Git aggiungendo +quanto segue al file #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +This enables you to use #{lso:}# anywhere you need to specify the address of +a #{live-systems.org}# git repository. If you also drop the optional +#{.git}# suffix, starting a new image using this configuration is as easy +as: + +code{ + + $ lb config --config lso:live-images + +}code + +Clonando l'intero repository #{live-images}# si ottengono configurazioni +usate per svariate immagini. Se dopo aver terminato la prima si vuole creare +un'immagine differente, basterà cambiare directory e opzionalmente fare di +nuovo le modifiche necessarie alle proprie esigenze. + +In ogni caso ricordarsi che ogni volta si dovrà creare l'immagine come +utente root: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/it/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/it/user_overview.ssi new file mode 100644 index 0000000..2a744b7 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/it/user_overview.ssi @@ -0,0 +1,132 @@ +:B~ Panoramica degli strumenti + +1~overview-of-tools Panoramica degli strumenti + +This chapter contains an overview of the three main tools used in building +live systems: live-build, live-boot and live-config. + +2~live-build Il pacchetto live-build + +live-build is a collection of scripts to build live systems. These scripts +are also referred to as "commands". + +L'idea dietro live-build è di essere un'infrastruttura che utilizza una +directory di configurazione per automatizzare totalmente e personalizzare +tutti gli aspetti della creazione di un'immagine live. + +Molti concetti sono simili a quelli applicati per creare pacchetti Debian +con /{debhelper}/: + +_* The scripts have a central location for configuring their operation. In +/{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For +example, dh_install will look, among others, for a file called +#{debian/install}# to determine which files should exist in a particular +binary package. In much the same way, live-build stores its configuration +entirely under a #{config/}# subdirectory. + +_* Gli script sono indipendenti, vale a dire che è sempre sicuro eseguire +ogni comando. + +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton +configuration directory. This could be considered to be similar to tools +such as /{dh-make}/. For more information about these tools, read on, since +the remainder of this section discuses the four most important +commands. Note that the preceding #{lb}# is a generic wrapper for live-build +commands. + +_* *{lb config}*: Responsible for initializing a Live system configuration +directory. See {The lb config command}#lb-config for more information. + +_* *{lb build}*: responsabile di iniziare la creazione di un sistema +live. Si veda {Il comando lb}#lb-build per maggiori informazioni. + +_* *{lb clean}*: responsabile della rimozione di parti della creazione di un +sistema live. Si veda {Il comando lb clean}#lb-clean per maggiori +informazioni. + +3~lb-config Il comando #{lb config}# + +As discussed in {live-build}#live-build, the scripts that make up live-build +read their configuration with the #{source}# command from a single directory +named #{config/}#. As constructing this directory by hand would be +time-consuming and error-prone, the #{lb config}# command can be used to +create the initial skeleton configuration tree. + +Issuing #{lb config}# without any arguments creates the #{config/}# +subdirectory which is populated with some default settings in configuration +files, and two skeleton trees named #{auto/}# and #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Using #{lb config}# without any arguments would be suitable for users who +need a very basic image, or who intend to provide a more complete +configuration via #{auto/config}# later (see {Managing a +configuration}#managing-a-configuration for details). + +Normally, you will want to specify some options. For example, to specify +which package manager to use while building the image: + +code{ + + $ lb config --apt aptitude + +}code + +È possibile specificare molte opzioni, come: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +Una lista completa delle opzioni è disponibile nel manuale di #{lb_config}#. + +3~lb-build Il comando #{lb build}# + +Il comando #{lb build}# legge la configurazione dalla directory #{config/}# +ed esegue a un livello inferiore i comandi necessari a costruire il sistema +live. + +3~lb-clean Il comando #{lb clean}# + +It is the job of the #{lb clean}# command to remove various parts of a build +so subsequent builds can start from a clean state. By default, #{chroot}#, +#{binary}# and #{source}# stages are cleaned, but the cache is left +intact. Also, individual stages can be cleaned. For example, if you have +made changes that only affect the binary stage, use #{lb clean --binary}# +prior to building a new binary. If your changes invalidate the bootstrap +and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or +#{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man +page for a full list of options. + +2~live-boot Il pacchetto live-boot + +live-boot is a collection of scripts providing hooks for the +/{initramfs-tools}/, used to generate an initramfs capable of booting live +systems, such as those created by live-build. This includes the live system +ISOs, netboot tarballs, and USB stick images. + +All'avvio cercherà supporti in sola lettura che contengano una directory +#{/live/}# dove sia presente un filesystem root (spesso un'immagine +compressa come squashfs). Se trovata, creerà un ambiente scrivibile usando +aufs, per avviarsi da sistemi simili a Debian. + +Si possono trovare maggiori informazioni sui ramfs iniziali nel capitolo su +initramfs del Debian Linux Kernel Handbook all'indirizzo +http://kernel-handbook.alioth.debian.org/. + +2~live-config Il pacchetto live-config + +live-config è costituito da script eseguiti all'avvio dopo live-boot per +configurare automaticamente il sistema live. Gestisce attività quali +impostare l'hostname, localizzazione e fuso orario, creare l'utente live, +inibire compiti automatizzati tramite cron ed eseguire il login automatico +dell'utente live. diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/about_manual.ssi new file mode 100644 index 0000000..3617fbe --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/about_manual.ssi @@ -0,0 +1,218 @@ +:B~ このマニュアルについて + +1~about-manual このマニュアルについて + +このマニュアルは ${project}と、特に Debian +9.0「${stable}」リリースに向けてプロジェクトにより作られるソフトウェアに関連するあらゆる文書にアクセスするための一元的な起点となります。最新版は常に +http://live-systems.org/ にあります。 + +Live マニュアルは第一に Live +システムのビルドの支援を扱い、エンドユーザ向けの話題は扱いませんが、エンドユーザにとって有用な情報がいくらかあるかもしれません: +{基本}#the-basics ではビルド済みイメージのダウンロードや、ウェブビルダーを使うかシステム上の live-build +を直接実行することでメディアやネットワークからイメージをブートさせる準備について触れています。{実行時の挙動の変更}#customizing-run-time-behaviours +では、キーボードレイアウトやロケールの選択、再起動をまたいで状態を引き継がせる仕組みの利用等、ブートプロンプトで指定できるオプションをいくらか説明しています。 + +提示されているコマンドの一部にはスーパーユーザ権限で実行しなければならないものもあります。これは #{su}# で root +ユーザになるか、#{sudo}# +を使って実行します。権限のないユーザで実行できるコマンドと実行にスーパーユーザ権限を必要とするコマンドは、それぞれのコマンドの前に #{$}# があるか +#{#}# があるかで区別します。この記号はコマンドの一部ではありません。 + +2~ せっかちな人向け + +このマニュアルにある全てが、少なくとも一部のユーザにとって重要だと確信していますが、触れている内容が多岐にわたることや、詳細を掘り下げるよりも先に、まずはソフトウェアをうまく使う経験をしたいであろうということをわかっています。したがって、以下の順に読み進めることを提案します。 + +最初にこの章{このマニュアルについて}#about-manual を始めから{用語}#terms 節まで読んでください。次に{例}#examples +節の最初にある3つのチュートリアルまで飛ばします。ここではイメージのビルドと独自化の基本について教えるようになっています。{例の使用}#using-the-examples +を最初に読み、引き続いて {チュートリアル 1: デフォルトイメージ}#tutorial-1 と {チュートリアル 2: +ウェブブラウザユーティリティ}#tutorial-2 を、最後に {チュートリアル 3: 私的イメージ}#tutorial-3 +を読んでください。チュートリアル群を終えるまでに、Live システムでできることが何なのかわかってくるでしょう。 + +それから戻り、マニュアルをもっと掘り下げて学習していくことを勧めています。恐らく、その次は{基本}#the-basics を読み、{netboot +イメージのビルド}#building-netboot-image に軽く目を通して、{独自化概要}#customization-overview +とそれに続く章を読んで終えるのがいいでしょう。この時点までに、Live +システムでできることを知ることがすっかり面白くなってマニュアルの残りを隅から隅まで読む気になっていることを期待します。 + +2~terms 用語 + +_* *{Live システム}*: ハードドライブにインストールしなくてもブートできるオペレーティングシステムです。Live +システムはそのコンピュータのハードドライブに既にインストールされているローカルのオペレーティングシステムやファイルを、そうするように指示しない限り改変しません。Live +システムは通常、CDやDVD、USBメモリ等のメディアからブートされます。ネットワーク越しにブートできるもの (netboot +イメージ経由、{netboot イメージのビルド}#building-netboot-image 参照) やインターネット越しにブートできるもの +(起動パラメータ #{fetch=URL}# 経由、{Webbooting}#webbooting 参照) もあります。 + +_* *{Live メディア}*: Live システムとは異なり、Live メディアは live-build により作成されたバイナリを書き込んでその +Live システムをブートするのに利用するCDやDVD、USBメモリを指します。もっと広い意味では、この語はネットワークブートファイルの位置等、Live +システムをブートする目的でこのバイナリが置かれている任意の場所を指すこともあります。 + +_* *{${project}}*: live-boot、live-build、live-config、live-tools、live-manual +パッケージを特に保守しているプロジェクトです。 + +_* *{ホストシステム}*: Live システムの作成に利用される環境です。 + +_* *{ターゲットシステム}*: Live システムの実行に利用される環境です。 + +_* *{live-boot}*: Live システムのブートに利用するスクリプト集です。 + +_* *{live-build}*: 独自化した Live システムのビルドに利用するスクリプト集です。 + +_* *{live-config}*: Live システムのブート処理中の設定に利用するスクリプト集です。 + +_* *{live-tools}*: 実行中の Live システム内で有用なタスクを実行するのに利用する追加のスクリプト集です。 + +_* *{live-manual}*: この文書は live-manual というパッケージで保守されています。 + +_* *{Debian Installer (d-i)}*: 公式の Debian ディストリビューション用インストールシステムです。 + +_* *{ブートパラメータ}*: bootloader プロンプトで入力し、カーネルや live-config の動作を変更できるパラメータです。 + +_* *{chroot}*: /{chroot}/ プログラム。#{chroot(8)}# により、単一のシステム上で異なる GNU/Linux +環境を再起動せずに並行して実行できるようになります。 + +_* *{バイナリイメージ}*: live-image-i386.hybrid.iso や live-image-i386.img 等、Live +システムを収録するファイルです。 + +_* *{ターゲットディストリビューション}*: Live +システムがベースとするディストリビューションです。これはホストシステムのディストリビューションとは別のものです。 + +_* *{安定版 (stable)/テスト版 (testing)/不安定版 (unstable)}*: *{安定版 (stable)}* +ディストリビューション、現在のコード名${stable}には、公式にリリースされた最新の Debian ディストリビューションが含まれます。*{テスト版 +(testing)}* ディストリビューション、一時的コード名 ${testing} は次期*{安定版 (stable)}* +リリースを集める場です。このディストリビューションを使う主な利点はソフトウェアのバージョンが*{安定版 (stable)}* +リリースと比べて新しいということです。*{unstable}* ディストリビューション、恒久的コード名 sid は Debian +の開発が活発に行われる場です。通常、このディストリビューションは開発者や、苦労をいとわず最新版を使いたい人が利用します。マニュアル全体を通して、リリースを指すのに +${testing} や sid 等のコード名を使っています。それこそが、ツール自体がサポートしているものだからです。 + +2~ 著者 + +著者一覧 (アルファベット順): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute この文書への貢献 + +このマニュアルの作成はコミュニティ中心のプロジェクトで、改善提案や貢献は全て、非常に歓迎されます。コミットキーの取得方法や良いコミットを行うための詳細な情報については、{プロジェクトへの貢献}#contributing-to-project +節を見てください。 + +3~applying-changes 変更の適用 + +マニュアルの英語版に変更を加える場合、#{manual/en/}# +にある正しいファイルを編集しないといけませんが、その貢献を提出する前に出来上がりを確認してください。Live マニュアルの出来上がりを確認する際は、 + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +を実行してビルドに必要なパッケージがインストールされていることを確認してください。Gitにより取得した最上位のディレクトリから + +code{ + + $ make build + +}code + +サポートされている全言語のマニュアルをビルドするのにはある程度時間がかかるため、著者が英語版のマニュアルに追加した新しい文書について見直す場合は見直し用に処理を省略させると好都合かもしれません。#{PROOF=1}# +を使うと HTML 形式の live-manual をビルドしますが分割版の HTML ファイルを作成しません。#{PROOF=2}# +を使うとPDF形式の live-manual をビルドしますがA4とレター縦だけです。これが #{PROOF=}# +を指定すると時間の節約が見込める理由です。例えば: + +code{ + + $ make build PROOF=1 + +}code + +翻訳の一つを見直す場合に一つの言語だけをビルドすることもできます。例えば: + +code{ + + $ make build LANGUAGES=ja + +}code + +を実行します。文書の種類を指定してビルドすることもできます。例えば + +code{ + + $ make build FORMATS=pdf + +}code + +あるいは両方を組み合わせて + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +修正が済んで全て良くなったらコミットですが、そのコミットで翻訳を更新するのでない限り #{make commit}# +を使わないようにしてください。また、その場合にマニュアルの英語版への変更と翻訳を一度にコミットするのではなく、それぞれ分けてコミットするようにしてください。さらなる詳細については{翻訳}#translation +節を見てください。 + +3~translation 翻訳 + +live-manual +を翻訳するには、新しく最初から翻訳を開始するのか、それとも既に存在する翻訳について作業を続けるのか、によって以下の手順を追ってください: + +_* 新しく最初から翻訳を開始する + +_2* #{manual/pot/}# にある +*{about_manual.ssi.pot}*、*{about_project.ssi.pot}*、*{index.html.in.pot}*ファイルを +(/{poedit}/ 等) 好みのエディタで自分の言語に翻訳し、整合性確認のため翻訳した #{.po}# +ファイルをメーリングリストに送ってください。live-manual の整合性確認では #{.po}# ファイルが 100% +翻訳されていることだけではなく誤りの可能性を検出します。 + +_2* 確認が済んだ後は、自動ビルドでの新しい言語の有効化は最初の翻訳済みファイルを #{manual/po/${言語}/}# に追加して #{make +commit}# を実行すれば十分です。それから #{manual/_sisu/home/index.html}# を編集して言語の名前と () +内にその英語名を追加してください。 + +_* 既に存在する翻訳について作業を続ける + +_2* 対象の言語が既に追加されている場合は、(/{poedit}/ 等) 好みのエディタで #{manual/po/}# にある残りの po +ファイルを手当たり次第に翻訳を続けてください。 + +_2* 翻訳済みマニュアルが .po ファイルから更新されていることを確実にするためには #{make commit}# +を行う必要があることと、#{git add .}#、#{git commit -m "Translating..."}#、#{git push}# +を実行する前に #{make build}# を実行すると変更を確認できるということを忘れないでください。#{make build}# +には相当の時間がかかる可能性があるため、{変更の適用}#applying-changes +で説明しているように、見直しの際は1つの言語だけをビルドして確認できることを覚えておくといいでしょう。 + +#{make commit}# +を実行するとテキストがいくらか流れていくのを目にするでしょう。これは基本的に処理状態についての情報を示すメッセージで、Live +マニュアルの改善のために何ができるのかということを知る手がかりにもなります。致命的エラーが起きていない限り、通常はそのまま進めて貢献を提出できます。 + +Live マニュアルには、翻訳者が未翻訳や変更された文字列を検索するのを大きく支援する2つのユーティリティが付属しています。1つ目は「make +translate」です。これは各 .po ファイル中にどれだけ未翻訳文字列があるのか、詳細を報告するスクリプトを実行します。2つ目は「make +fixfuzzy」で、こちらは変更された文字列だけを対象としますが、1つ1つ見つけて修正する作業を支援します。 + +こういったユーティリティはコマンドラインで翻訳作業を行うのには実際に役立つかもしれませんが、推奨する作業方法は /{poedit}/ +のような専用ツールの利用だということに留意してください。Debian 地域化 (l10n) 文書や、特に Live +マニュアル向けの{翻訳者向けのガイドライン}#guidelines-translators を読むのも良いことです。 + +*{注意:}* gitツリーを push する前に #{make clean}# を実行してきれいにすることができます。この手順は .gitignore ファイルのおかげで強制ではありませんが、ファイルを意図せずコミットすることを避けられる良い実践となります。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/about_project.ssi new file mode 100644 index 0000000..f458c27 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/about_project.ssi @@ -0,0 +1,85 @@ +:B~ ${project}への貢献 + +1~about-project ${project}について + +2~ 動機 + +3~ 現在の Live システムの問題点 + +${project}が始まったとき、利用可能な Debian ベースの Live システムは既に複数あり、素晴らしい作業を行っていました。Debian +の視点から見て、そのほとんどには以下のような不満があります。 + +_* Debian のプロジェクトではないために Debian でのサポートがない。 + +_* 異なるディストリビューション、例えば*{安定版 (testing)}* と*{不安定版 (unstable)}* を混ぜて使っている。 + +_* サポートしているのが i386 だけ。 + +_* 容量節約のためにパッケージの挙動や見た目を変更している。 + +_* Debian アーカイブ外のパッケージを収録している。 + +_* Debian のものではない追加パッチを適用した独自カーネルを使っている。 + +_* 本体のサイズのために巨大で遅く、レスキュー用途に合わない。 + +_* 異なる形式、例えば CD、DVD、USB メモリ、netboot イメージから利用できない。 + +3~ 自身の Live システムを作成する理由 + +Debian はユニバーサルオペレーティングシステムです: Debian に Live システムがあることで Debian +システムを案内、正確に表現することができるとともに、主に以下の利点があります: + +_* これは Debian のサブプロジェクトです。 + +_* 単一のディストリビューションの (現在の) 状態を反映します。 + +_* 可能な限り多くのアーキテクチャで動作します。 + +_* 変更しない Debian パッケージだけで構成されます。 + +_* Debian アーカイブにないパッケージは何も含まれません。 + +_* 改変しない Debian のカーネルを追加パッチなしで利用します。 + +2~ 哲学 + +3~ Debian「main」の変更しないパッケージしか使いません + +「main」Debian リポジトリのパッケージだけを利用します。「non-free」は Debian の中には含まれないため、公式の Live +システムのイメージでは利用できません。 + +いかなるパッケージも変更しません。何か変更が必要であれば Debian のそのパッケージのメンテナと調整を行います。 + +例外として、live-boot や live-build、live-config といった私達の独自のパッケージを開発用の目的 +(例えば開発用スナップショットの作成) のため私達自身のリポジトリから一時的に利用するかもしれません。このパッケージ群は定期的に Debian +にアップロードされます。 + +3~ Live システム固有のパッケージ設定はありません + +現段階で、インストール例や代替設定は組み込んでいません。パッケージが利用されるのは Debian +を普通にインストールした後のものなので全てデフォルト設定です。 + +別のデフォルト設定が必要であれば Debian のそのパッケージのメンテナと調整を行います。 + +debconf を使うことで提供されるパッケージ設定システムにより、独自に作成した Live +システムのイメージを使って独自に設定したパッケージをインストールすることができるようになりますが、{ビルド済み Live +イメージ}#downloading-prebuilt-images では Live +環境で動作させるために絶対に必要だという場合を除いて、パッケージをそのデフォルト設定のままにすることを選択しました。Live +用ツールチェインや{ビルド済みイメージ設定}#clone-configuration-via-git への変更よりも、そこで可能である限り、Debian +アーカイブにあるパッケージを Live +システムでよりよく動作させることを好みます。さらなる情報については、{独自化概要}#customization-overview を見てください。 + +2~contact 連絡先 + +_* *{メーリングリスト}*: プロジェクトの第一の連絡先は https://lists.debian.org/debian-live/ +のメーリングリストです。debian-live@lists.debian.org +宛てのメールにより、メーリングリストに直接メールを送ることができます。メーリングリストのアーカイブは +https://lists.debian.org/debian-live/ で利用できます。 + +_* *{IRC}*: ユーザや開発者達が irc.debian.org (OFTC) の #debian-live +チャンネルにいます。IRCで質問するときは静かに回答を待ってください。回答が得られないときはメーリングリストにメールで質問してください。 + +_* *{BTS}*: {Debian バグ追跡システム}https://www.debian.org/Bugs/ (BTS) +には、ユーザや開発者により報告されたバグの詳細があります。バグにはそれぞれに番号が与えられ、対処されたものとして指示するまで存在するバグとして扱われます。さらなる情報については{バグの報告}#bugs +を見てください。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/appendix_style-guide.ssi new file mode 100644 index 0000000..d86d370 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/appendix_style-guide.ssi @@ -0,0 +1,263 @@ +:B~ スタイルガイド + +1~style-guide スタイルガイド + +2~ 著者向けガイドライン + +この節では Live マニュアル向けの技術的文書を記述する際に一般的に考慮すべき事項を扱います。言語特性と推奨手順に分かれています。 + +*{注意:}* 著者はまず{この文書への貢献}#how-to-contribute を読んでください + +3~ 言語特性 + +_* /{平易な英語を使う}/ + +読み手は英語が母国語ではない人の割合が高いことに留意してください。そのため、一般的規則として短く有意な文章を使い、引き続いて終止符を打ってください。 + +これは単純で幼稚な書き方をするように言っているわけではありません。英語が母国語ではない人にとって理解しにくい複雑な従属文にすることを可能な限り避けましょうという提案です。 + +_* /{英語の方言}/ + +最も広く使われている英語の方言はイギリス英語とアメリカ英語なので、ほとんどの著者が非常に高い率でこのどちらかを使っています。共同作業環境下で理想的なのは「国際英語」ですが、既存の全ての方言からどれを使うのが最善なのか決定するのは不可能とは言いませんが非常に困難です。 + +誤解を生まずに複数の方言を混在させることもできるとは思いますが、一般論として一貫性を持たせるようにすべきで、また、イギリス英語やアメリカ英語、その他の英語の方言からどれを使うか自分の裁量で決める前に、他の人がどのように書いているのかを調べてそれを真似るようにしてください。 + +_* /{バランス良く}/ + +偏見を持たないようにしてください。Live +マニュアルに全く関係のない思想への言及を引用することは避けてください。技術的文献は可能な限り中立であるべきです。科学的文献では中立こそが自然です。 + +_* /{政治的に正しく}/ + +性差を表す言葉を可能な限り避けるようにしてください。個人の第三者を持ち出す必要がある場合は「he (彼)」や「she (彼女)」、あるいは「s/he や +s(he) 彼(女)」などと複雑にするよりも「they (彼ら)」を使うのが好ましいです。 + +_* /{簡潔に}/ + +要点を直接述べ、回りくどい表現を使わないようにしてください。必要な情報は十分に提示ながらも、必要以上の余計な情報を提示するのはやめてください。これは不要な詳細を説明しないようにということです。読み手には理解力があります。読み手の側にいくらか前提知識があることを仮定してください。 + +_* /{翻訳作業を最小限に}/ + +書かれたものは他の複数の言語に翻訳されることになるということに留意してください。これは無意味あるいは冗長な情報を追加するとその分余計な作業をする人が出てくるということを意味します。 + +_* /{一貫性を}/ + +前にも提案しましたが、共同作業の文書を標準化して全体を完全に統一することはほぼ不可能です。しかし、文書を書く際に全体を通して他の著者と一貫した書き方をすることを歓迎します。 + +_* /{結束性を}/ + +必要なだけ文脈形成句を使い、文章に結束性を持たせて明確にしてください (文脈形成句は接続語句等の言語標識です)。 + +_* /{記述的に}/ + +標準的な「changelog」形式で文を単に羅列するよりも段落を使って要点を説明する方が好ましいです。描写してください! +読み手はそれを歓迎するでしょう。 + +_* /{辞書}/ + +英語で特定の概念を表現する方法がわからないときは辞書や百科事典でその語の意味を調べてください。ただし、辞書は最高の友ですが正しい使い方を知らなければ最悪の敵にもなることに留意してください。 + +英語には最大の語彙が存在する言語の一つです +(100万語以上)。この語の多くは他の言語から取り入れられたものです。単語の意味を二カ国語の辞書で調べる際、英語が母国語ではない人は母国語の言葉により似ているものを選択する傾向があります。このことにより、英語ではあまり自然に聞こえない、過度に形式ばった文体になりがちです。 + +原則として、ある概念が複数の異なる同義語により表現できるとき、辞書で最初に提示された語を選択するのが良い判断となるでしょう。疑問がある場合はゲルマン起源の語 +(通常単音節の語) +を選択すると多くの場合正しいとなります。この2つの技ではどちらかというとくだけた表現になるかもしれないという点には注意が必要ですが、少なくとも広く使われていて通常受け入れられる語を選択することになります。 + +共起辞書の利用を勧めます。通常合わせて利用する語がわかるようになると極めて役に立ちます。 + +繰り返しますが、他の人の作業から学ぶことが最良の実践です。検索エンジンを使って他の著者が特定の表現をどのように使っているか確認することは大きな手助けとなるでしょう。 + +_* /{空似言葉や熟語その他の慣習的な表現}/ + +空似言葉に気をつけてください。外国語の熟練度を問わず、2つの言語で同じように見える語だけれどもその意味や使い方が全く異なる「空似言葉」という罠にはまることがあることは避けられません。 + +熟語は可能な限り避けてください。「熟語」は個々の語が持っていた意味とは完全に異なる意味を表すことがあります。熟語は英語が母国語の人でさえ理解しにくいこともあります! + +_* /{俗語や省略、短縮表現等は避けましょう}/ + +平易な、日常的な英語の使用を勧めるとはいっても、技術的文献は言語を正式に記録する類のものです。 + +俗語や通常使わない解釈困難な省略表現、特に母国語での表現を模倣するような短縮表現は避けてください。IRCや、家族や仲間内で使うような特有の表現での記述はしないでください。 + +3~ 手順 + +_* /{書く前にテストを}/ + +著者が Live マニュアルに追加する前に例をテストして、全て確実に説明通りに動作するようにすることは重要です。きれいな chroot +やVM環境でのテストが良い起点となるでしょう。他に、それから異なるハードウェアを使っている異なるマシンでテストを実施し、起きるであろう問題を発見することができれば理想でしょう。 + +_* /{例}/ + +例示するときはできるだけ具体的にするようにしてください。例は結局例でしかありませんから。 + +抽象的な表現で読み手を混乱させるよりも、特定の状況でのみ適用できるような書き方をする方がより良いことはよくあります。この場合は提示した例の効果を簡単に説明することもできます。 + +使い方を誤ればデータ消失や類似の望ましくない影響を及ぼす可能性のある、潜在的に危険なコマンド類の使用を例示する場合等、例外がいくらかあります。この場合は起こりうる副作用について十分な説明を提供すべきです。 + +_* /{外部リンク}/ + +外部サイトへのリンクは、そのサイトにある情報が特別な点を理解するために決定的な効果が期待できる場合にのみ利用すべきです。その場合でも、外部サイトへのリンクは可能な限り少なくしてください。インターネット上のリンクはその内容がほとんどが変更される可能性があるもので、その結果機能しないリンクができたり、論拠を不完全な状態にしてしまうことになります。 + +他に、インターネットに接続せずにそのマニュアルを読んでいる人にはそのリンクを追う機会がありません。 + +_* /{商標の主張やマニュアルの公開にあたって採用したライセンスに違反するものは避ける}/ + +商標の主張は可能な限り避けてください。記述した文書は他の下流のプロジェクトで使うことになるかもしれないことに留意してください。つまり、ある種の特定の内容を追加することは事態を複雑にすることになります。 + +live-manual は GNU GPL の条件下で使用を許可しています。これには、合わせて公開する (著作権のある画像やロゴを含むあらゆる種類の) +内容の配布物に適用する意味合いがいくつかあります。 + +_* /{まず草稿を書き、改訂、変更して改善し、必要なら作り直す}/ + + - 案を引き出しましょう! まず論理的に順を追って考えを整理する必要があります。 + + - 頭の中で何とか形ができたら最初の草稿を書きます。 + + - 文法や書式、つづりを直します。リリースの正しい名前は ${testing} や sid + で、これをコード名として参照するときは大文字にすべきではないことに留意してください。「spell」ターゲットを使って、つまり#{make + spell}#でつづりの誤りがないか確認できます。 + + - 記述を改善し、必要な部分があれば書き直します。 + +_* /{章}/ + +章や副題には慣習的な番号の付け方をしてください。例えば 1、1.1、1.1.1、1.1.2 ... 1.2、1.2.1、1.2.2 ... 2、2.1 +... などというようにです。以下のマークアップを見てください。 + +説明するのに一連の手順や段階を列挙する必要がある場合は、First (最初に)、second (2つ目に)、third (3つ目に) +... というように序数を使ったり、First (最初に)、Then (それから)、After that (その後)、Finally +(最後に)、... あるいは箇条書きすることもできます。 + +_* /{マークアップ}/ + +大事なことを言い忘れましたが、live-manual では {SiSU}http://www.sisudoc.org/ +を使ってテキストファイルを処理し、複数の形式の出力を生成しています。{SiSU +マニュアル}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html +を眺めてそのマークアップ方法をよく理解することを勧めます。代わりに + +code{ + + $ sisu --help markup + +}code + +と入力する方法もあります。マークアップをいくらか例示してみます。有用だということはわかるかもしれません。 + + - 文字列の強調/太字: + +code{ + +*{foo}* または !{foo}! + +}code + +は「*{foo}* または !{foo}!」となります。これは特定のキーワードを強調するのに使います。 + + - 斜体: + +code{ + +/{foo}/ + +}code + +は /{foo}/ となります。これは例えば Debian パッケージの名前に使います。 + + - 等幅: + +code{ + +#{foo}# + +}code + +は #{foo}# となります。これは例えばコマンドの名前に使います。また、キーワードやパスのようなものの一部を強調するのにも使います。 + + - コードブロック: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +は + +code{ + + $ foo + # bar + +}code + +となります。タグの開始には #{code{}# を、終了には #{}code}# +を使います。コードの各行には先頭に空白が必要だということを必ず覚えておいてください。 + +2~guidelines-translators 翻訳者向けガイドライン + +この節では Live マニュアルの内容を翻訳する際に一般的に考慮すべき事項を扱います。 + +一般的な推奨事項として、翻訳者は自分の言語に適用される翻訳規則を既に読んで理解しておくべきです。通常、翻訳用のグループやメーリングリストが Debian +の品質標準に合致する翻訳物を作成する方法についての情報を提供しています。 + +*{注意:}* 翻訳者は{この文書への貢献}#how-to-contribute も読むべきです。特に{翻訳}#translation 節を + +3~ 翻訳の手がかり + +_* /{コメント}/ + +翻訳者の役割は元の著者により書かれた語や文、段落、そして文章の意味を可能な限り忠実に目標の言語で伝えることです。 + +そのため、個人的なコメントや自分の余計な情報の追加は控えるべきです。同一の文書について作業している他の翻訳者に向けてコメントを追加したい場合はそのために用意されている場があります。これは +*{po}* ファイルの番号記号 *{#}* +に続く文字列のヘッダです。ほとんどの視覚的な翻訳用プログラムで自動的にこれをコメントの種類に属するものとして処理します。 + +_* /{TN, Translator's Note (翻訳者によるメモ)}/ + +完全に受け入れられるとはいえ、翻訳済みテキストの括弧「()」内に語や表現を含めることは、ややこしい語や表現の意味を読み手にとってより明確にする場合にのみ行ってください。翻訳者は括弧内に「(訳注)」等と記載して、その追記が翻訳者によるものであることを明確にすべきです。 + +_* /{非人称の文を}/ + +英語で書かれた文書は「you」を非人称として幅広く使います。他の言語にはこの特徴を共有しないものもあります。このことで、元の文が読み手に対して直接呼びかけているかのような誤った印象を実際にはそうではないのに与えてしまうかもしれません。翻訳者はこの点に注意して、可能な限り正確に自分の言語に反映する必要があります。 + +_* /{空似言葉}/ + +前に説明した「空似言葉」の罠は特に翻訳者に当てはまります。疑いがあれば、その疑わしい空似言葉の意味を再点検してください。 + +_* /{マークアップ}/ + +最初は*{pot}*ファイル、後には*{po}*ファイルについて作業する翻訳者は多数のマークアップ機能を文字列に確認できるでしょう。文は翻訳できるものである限り翻訳できますが、それが元の英語版と全く同一のマークアップを採用しているということは極めて重要です。 + +_* /{コードブロック}/ + +コードブロックは通常翻訳できませんが、翻訳にそれを含めることが、翻訳率 100% +を達成する唯一の方法です。コードが変更されると翻訳者による介入が必要となるため最初は余計な作業になりますが、長期的に見るとこれが .po +ファイルの整合性を確認したときに何が既に翻訳済みで何が未翻訳なのか識別する最善の方法です。 + +_* /{改行}/ + +翻訳文には元の文と全く同じだけの改行が必要です。元のファイルに改行があるときは注意して「Enter」キーを押すか*{\n}*を打ち込んでください。改行は例えばコードブロック中でよく使われます。 + +勘違いしないでください。これは翻訳文を英語版と同一の長さにする必要がある、ということではありません。それはほぼ不可能です。 + +_* /{翻訳できない、してはいけない文字列}/ + +翻訳者が決して翻訳すべきでないもの: + + - リリースのコード名 (小文字で書くべき) + + - プログラムの名前 + + - 例示するコマンド + + - メタ情報 (前後にコロンが置かれることが多い *{:メタ情報:}*) + + - リンク + + - パス diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/examples.ssi new file mode 100644 index 0000000..1d6fa99 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/examples.ssi @@ -0,0 +1,383 @@ +:B~ 例 + +1~examples 例 + +この章では特定の Live システム活用事例向けの見本ビルドについて触れます。自分用の Live +システムイメージのビルドが初めてであれば、まず3つのチュートリアルを順に調べてみることを勧めます。それぞれで他の例の利用、理解を支援する新しい技術を学ぶようになっているためです。 + +2~using-the-examples 例の使用 + +提示している例を利用するためには、ビルドするために{要件}#requirements +に記載されている要件一覧に合致するシステムと、{live-build のインストール}#installing-live-build で説明しているように +live-build がインストールされていることが必要となります。 + +簡潔にするため、ここに挙げる例ではビルドで利用するローカルミラーを指定していないことに注意してください。ローカルミラーを利用するとダウンロード速度をかなり高速化できます。{ビルド時に利用するディストリビューションのミラー}#distribution-mirrors-build-time +で説明しているように、#{lb config}# を使った場合はオプションを指定することができます。ビルドシステムのデフォルト値を +#{/etc/live/build.conf}# でセットするともっと便利になります。このファイルを単純に作成し、対応する +#{LB_MIRROR_*}# +変数に望ましいミラーをセットしてください。ビルドで利用する他のミラーは全て、これにより設定した値をデフォルト値として使います。例えば: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 チュートリアル 1: デフォルトイメージ + +*{事例:}* 簡単な最初のイメージを作成して live-build の基礎を学びます。 + +このチュートリアルでは、live-build を利用した最初の演習としてbase パッケージ (Xorg は含まない) と Live +システムを支援するパッケージだけを収録する、デフォルトの ISO hybrid 形式の Live システムイメージをビルドします。 + +これ以上簡単にすることはなかなかできないでしょう: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +何か望むことがあれば #{config/}# +ディレクトリの内容を調べてください。ここには概略の設定があり、すぐ独自化もできますが、ここではそのままでデフォルトのイメージをビルドします。 + +スーパーユーザでイメージをビルドし、そのログを #{tee}# により保存します。 + +code{ + + # lb build 2>&1 | tee build.log + +}code + +すべてがうまくいくとして、しばらくすると現在のディレクトリに #{live-image-i386.hybrid.iso}# が出来上がります。この +ISO hybrid イメージは {Qemu でのISOイメージのテスト}#testing-iso-with-qemu や {VirtualBox +でのISOイメージのテスト}#testing-iso-with-virtualbox +で説明しているように仮想マシンで直接、あるいは{物理メディアへのISOイメージ書き込み}#burning-iso-image や {USBメモリへの +ISO hybrid イメージのコピー}#copying-iso-hybrid-to-usb +で説明しているように光学メディアやUSBフラッシュ機器に書き込んだイメージ、それぞれからブートできます。 + +2~tutorial-2 チュートリアル 2: ウェブブラウザユーティリティ + +*{事例:}* ウェブブラウザユーティリティイメージを作成し、独自化の適用方法を学びます。 + +このチュートリアルでは Live システムイメージを独自化する方法の紹介として、ウェブブラウザユーティリティとしての利用に適するイメージを作成します。 + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +この例で LXDE +を選択しているのは最小限のデスクトップ環境を提供するという私達の目的を反映しています。念頭に置いているこのイメージの目的はただ一つ、ウェブブラウザだけだからです。もっと細かく、#{config/includes.chroot/etc/iceweasel/profile/}# +でのウェブブラウザ向けデフォルト設定やウェブ上の様々な種類の内容を表示するための追加のサポートパッケージを提供することはできますが、それは読み手の演習として残しておきます。 + +{チュートリアル 1}#tutorial-1 と同様、ここでもスーパーユーザでイメージをビルドし、ログを残します: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +ここでも{チュートリアル 1}#tutorial-1 と同様、イメージがうまくできているか検証し、テストします。 + +2~tutorial-3 チュートリアル 3: 私的イメージ + +*{事例:}* プロジェクトを作成して個人用イメージをビルドします。USBメモリを使って好みのソフトウェアを自由に収録し、要求や設定を変更しながらこのイメージを続けて改訂します。 + +この個人用イメージを何度も改訂し、変更を追跡しておいて実験的に試してみてうまくいかなかったときには差し戻せるようにしたいため、人気のある#{git}#バージョン管理システムに設定を残します。{設定管理}#managing-a-configuration +で説明している #{auto}# スクリプトによる自動設定を経由した最善の実践も利用します。 + +3~ 最初の改訂 + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +#{auto/config}# を以下のように変更します: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +#{lb config}# を実行して設定ツリーを生成し、生成された #{auto/config}# スクリプトを使います: + +code{ + + $ lb config + +}code + +ここでローカルパッケージ一覧を設定します: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +まず、#{--architectures i386}# により必ず #{amd64}# +ビルドシステムでほとんどのマシンでの利用に適応する32ビット版をビルドするようにします。次に、相当に古いシステムでのこのイメージの利用を想定しないため +#{--linux-flavours 686-pae}# を使います。/{lxde}/ +のタスクメタパッケージを選択して最小限のデスクトップを揃えます。最後に、好みのパッケージの初期値として /{iceweasel}/ と +/{xchat}/ を追加しています。 + +そして、イメージをビルドします: + +code{ + + # lb build + +}code + +最初の2つのチュートリアルとは異なり、#{2>&1 | tee build.log}# は #{auto/build}# +に書かれているため打ち込む必要がなくなっていることに注意してください。 + +({チュートリアル 1}#tutorial-1 にあるように) +イメージをテストしてうまく機能する確信を得たら#{git}#リポジトリを初期化し、作成したばかりの auto +スクリプトだけを追加し、最初のコミットを行います: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ 2回目の改訂 + +この改訂では、最初のビルドをきれいにし、/{vlc}/ パッケージを設定に追加して再ビルド、テストコミットを行います。 + +#{lb clean}# +コマンドは前のビルドで生成したファイルを、パッケージを再びダウンロードせずに済むようにキャッシュを除いて全てきれいにします。これにより以降の #{lb +build}# が全段階で再び実行され、必ず新しい設定でファイルを再生成するようになります。 + +code{ + + # lb clean + +}code + +/{vlc}/ パッケージを #{config/package-lists/my.list.chroot}# のローカルパッケージ一覧に追記します: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +再びビルドします: + +code{ + +# lb build + +}code + +テストして満足したら次の改訂としてコミットします: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +もちろん、#{config/}# +以下のサブディレクトリにファイルを追加する等により設定をもっと複雑に変更することも可能です。新しい改訂版をコミットする際、#{config}# +の最上位にある、#{LB_*}# 変数を設定しているファイルもビルドされてできたもので、#{lb clean}# と、対応する #{auto}# +スクリプトを経由して再作成した #{lb config}# により常に整理されるものなので、手で編集したりコミットすることのないように注意してください。 + +一連のチュートリアルもこれで終わりです。もっと多様な独自化はできますが、ここまでの簡単な例で見てきた少しの機能を使うだけでも、イメージはほぼ無限の異なる組み合わせを作成することができます。この節の残りの例では、収集してきた +Live システムのユーザの経験を元にした他の事例についていくつか触れます。 + +2~ VNC 公衆クライアント + +*{事例:}* live-build を使って、ブートすると直接 VNC サーバに接続するイメージを作成します。 + +ビルド用ディレクトリを作ってそこに概略設定を作成し、推奨パッケージを無効にして最小限のシステムを作成します。それから初期パッケージ一覧を2つ作成します: +1つ目は live-build により提供される #{Packages}# というスクリプト +({生成されるパッケージ一覧}#generated-package-lists 参照) により生成し、2つ目では +/{xorg}/、/{gdm3}/、/{metacity}/、/{xvnc4viewer}/ を収録します。 + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +{APT の調整による容量の節約}#tweaking-apt-to-save-space +で説明しているように、イメージが適切に機能するためには推奨パッケージを再びいくらか追加する必要があるかもしれません。 + +推奨パッケージ一覧を調べるための簡単な方法として /{apt-cache}/ の利用があります。例えば: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +この例では live-config 及び live-boot により推奨されるパッケージを複数、再び収録する必要があることがわかっています: +自動ログインが機能するためには #{user-setup}#、システムをシャットダウンするための不可欠なプログラムとして +#{sudo}#。他に、イメージをRAMにコピーできるようになる #{live-tools}# や Live メディアを最終的に取り出す +#{eject}# を追加しておくと便利でしょう。それを反映すると: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +その後ディレクトリ #{/etc/skel}# を #{config/includes.chroot}# に作成し、その中にデフォルトユーザ向けの独自の +#{.xsession}# を置きます。このファイルは /{metacity}/ を立ち上げて /{xvncviewer}/ +を起動し、#{192.168.1.2}# にあるサーバのポート #{5901}# に接続します: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +イメージをビルドします: + +code{ + + # lb build + +}code + +楽しみましょう。 + +2~ 128MB USB メモリ向けの基本イメージ + +*{事例:}* 128MB USB メモリに収まるように構成要素をいくらか削除して、収まることがわかるように容量を少し空けたデフォルトのイメージの作成。 + +特定のメディア容量に収まるようにイメージを最適化する場合、イメージのサイズと機能はトレードオフになることを理解する必要があります。この例では削るだけにしているので +128MB のメディアサイズ内に何か追加する余地をできるだけ残していますが、/{localepurge}/ +パッケージによるロケールの完全削除や収録しているパッケージ内の一貫性は何も壊していません。また、その他の「押し付ける」ような最適化もしていません。特に注目すべきなのは、最小限のシステムを最初から作成するために +#{--debootstrap-options}# を利用している点です。 + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +イメージを適切に機能させるためには、最低でも #{--apt-recommends false}# +オプションにより外されていた推奨パッケージを2つ追加しなおす必要があります。{APTの調整による容量の節約}#tweaking-apt-to-save-space +を見てください。 + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +ここで、普通の方法でイメージをビルドしてみます: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +これを書いている時点の著者のシステムでは、上記の設定により 110MB のイメージができました。これを{チュートリアル 1}#tutorial-1 +のデフォルト設定で作成された 192MB のイメージと都合良く比較してみましょう。 + +#{--apt-indices false}# によりAPTの索引を省くことでかなりの容量を節約していますが、その代わりに Live システムで +/{apt}/ を使う前に #{apt-get update}# を実行する必要があります。#{--apt-recommends false}# +により推奨パッケージを除外することで、本来あるはずのパッケージをいくらか除外する代わりにいくらか追加で容量を節約します。#{--debootstrap-options +"--variant=minbase"}# で最初から最小限のシステムを構成します。#{--firmware-chroot false}# +でファームウェアパッケージを自動的に収録しないようにすることでもさらに容量をいくらか節約します。そして最後に、#{--memtest none}# +によりメモリテスターのインストールを抑制します。 + +*{注意:}* 最小限のシステムの構成はフックを使って、例えば #{/usr/share/doc/live-build/examples/hooks}# にある #{stripped.hook.chroot}# でも実現できます。これは容量をさらに少し減らし、62MB のイメージを生成します。しかしこれはその実現のために、システムにインストールしたパッケージから文書その他のファイルを削除しています。これはそうしたパッケージの完全性を破壊し、ヘッダで警告しているように思わぬ結果をもたらすかもしれません。それが、この目標のために推奨するのが最小限の /{debootstrap}/ を利用する方法になっている理由です。 + +2~ 地域化した GNOME デスクトップとインストーラ + +*{事例:}* GNOME デスクトップのイメージを作成し、スイス用の地域化とインストーラを収録する + +好みのデスクトップを使った i386 アーキテクチャ向けの iso-hybrid イメージを作りたい。ここでは GNOME を使用して、GNOME +用の標準の Debian インストーラによりインストールされるのと同一のパッケージを全て収録します。 + +最初の問題は適切な言語用タスクの名前を判断する方法です。現在 live-build +はこれを支援できません。運良くこれを試行錯誤で見つけられるかもしれませんが、そのためのツールがあります。#{grep-dctrl}# を利用して +tasksel-data にあるタスクの説明を見つけることができます。そのため、準備としてこの両方が揃っていることを確認してください: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +これで適切なタスクを検索できるようになりました。まず、 + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +というコマンドにより、呼ばれたタスクが、簡単に言うとここではドイツだということがわかります。次は関連タスクを見つけます: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +ブート時に *{de_CH.UTF-8}* ロケールを生成して *{ch}* +のキーボードレイアウトを選択します。一緒に見ていきましょう。{メタパッケージの利用}#using-metapackages +から、タスクのメタパッケージには先頭に #{task-}# +が付くことを思いだしてください。こういった言語のブートパラメータを指定し、それから優先度が標準のパッケージと発見したタスクの全メタパッケージをパッケージ一覧に追加するだけです: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +のようになります。インストーラを Live デスクトップから立ち上げるために /{debian-installer-launcher}/ +パッケージを収録していることに注意してください。さらに、インストーラを立ち上げる機能が適切に動作するために現在必要な #{586}# +用のカーネルがデフォルトで収録されます。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/ja/live-manual.ssm new file mode 100644 index 0000000..4c41f9d --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Live システムマニュアル" + +creator: + author: "Live システムプロジェクト <debian-live@lists.debian.org>" + +rights: + copyright: "2006-2015 Live Systems Project" + license: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." + +date: + published: "2015-08-23" + +publisher: "Live システムプロジェクト <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live システムプロジェクト'" + +:A~ @title + +:B~ About + +<< about_manual.ssi + +<< about_project.ssi + +:B~ ユーザ + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ プロジェクト + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ 例 + +<< examples.ssi + +:B~ 付録 + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/project_bugs.ssi new file mode 100644 index 0000000..11018fb --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/project_bugs.ssi @@ -0,0 +1,156 @@ +:B~ バグの報告 + +1~bugs バグの報告 + +Live システムは完璧にはほど遠いですが、可能な限り完璧に近づけたいと思っています - +あなたの支援とともに。バグの報告を躊躇わないでください。バグがあるのに報告されないよりも二重に報告される方がいいからです。この章ではバグ報告を提出するにあたっての推奨事項について説明します。 + +せっかちな人向け: + +_* 常にまず http://live-systems.org/ にある私達のホームページにあるイメージの更新状況により既知の問題を確認してください。 + +_* バグ報告を提出する前に使用している live-build、live-boot、live-config、live-tools +のブランチの*{最新版}* (live-build 4 を使っているなら最新のバージョン 4.x の live-build) +でそのバグを再現できるか常に確認します。 + +_* バグについて*{できるだけ具体的な情報}*を提示するようにしてください。これには (最低限) 利用した +live-build、live-boot、live-config、live-tools のバージョンや Live +システムをどのディストリビューションでビルドしたのか、等があります。 + +2~ 既知の問題 + +Debian *{テスト版 (testing)}* と Debian *{不安定版 (unstable)}* +ディストリビューションは変化しているのでこのどちらかを対象システムディストリビューションに指定している場合、ビルドが常に成功するとは限りません。 + +% FIXME: + +そのためにあまり困難になる場合はビルドに*{テスト版 (testing)}* や*{不安定版 (unstable)}* +をベースにしたシステムではなく*{安定版 (stable)} を使ってください。live-build は常に*{安定版 (stable)}* +リリースをデフォルトとしています。 + +現在わかっている問題は http://live-systems.org/ にある私達のホームページの「status」に一覧があります。 + +開発用ディストリビューションのパッケージにある問題を正しく識別、修正するための訓練はこのマニュアルの目的ではありませんが、常に確認できることが2つあります: +*{テスト版 (testing)}* を対象ディストリビューションとしてビルドに失敗した場合に*{不安定版 (unstable)}* +で試してみるということです。*{不安定版 (unstable)}* でもダメな場合は*{テスト版 (testing)}* +に差し戻し、失敗しているパッケージのもっと新しいバージョンを*{不安定版 (unstable)}* から利用するようにしてみます (詳細については +{APTのPIN設定}#apt-pinning 参照)。 + +2~ 最初から再ビルド + +きれいではない環境でシステムがビルドされたことにより特定のバグが発生しているのではないことを保証するため、Live +システム全体を最初から再ビルドして、そのバグが再現するか常に確認してください。 + +2~ 最新のパッケージを使う + +問題を再現 (最終的には修正) +しようとするときに古くなったパッケージを使用すると重大な問題を引き起こす可能性があります。ビルドシステムが最新であること、同様にそのイメージに収録されているパッケージがどれも最新であることを確認してください。 + +2~collect-information 情報収集 + +報告では十分な情報を提供してください。最低でもそのバグが発生した live-build +の正確なバージョンとそれを再現する手順を含めてください。常識的に考えて問題解決の支援になりそうだと思う関連情報が何か他にあればそれも提供してください。 + +バグ報告を最大限に活用するため、最低限次の情報が必要です: + +_* ホストシステムのアーキテクチャ + +_* ホストシステムのディストリビューション + +_* ホストシステムの live-build のバージョン + +_* ホストシステムの /{debootstrap}/ のバージョン + +_* Live システムのアーキテクチャ + +_* Live システムのディストリビューション + +_* Live システムの live-boot のバージョン + +_* Live システムの live-config のバージョン + +_* Live システムの live-tools のバージョン + +#{tee}# コマンドを使ってビルドプロセスのログを生成することができます。#{auto/build}# +スクリプトによりこれを自動的に行うことを推奨します (詳細は{設定管理}#managing-a-configuration 参照)。 + +code{ + + # lb build 2>&1 | tee build.log + +}code + +ブート時に、live-boot と live-config はログファイルを #{/var/log/live/}# +に保存します。エラーメッセージはここを確認してください。 + +さらに、他のエラーを除外するため、#{config/}# ディレクトリを tar でまとめてどこかにアップロードするのは常に良い方法です +(メーリングリストに添付として送ら*{ないでください}*)。それにより、そのエラーの再現を試みることが可能になります。それが +(例えばサイズの問題により) 困難な場合は #{lb config --dump}# の出力を使ってください。これは設定ツリーのまとめです (つまり +#{config/}# のサブディレクトリにあるファイル一覧を列挙しますがファイル自体は収録しません)。 + +ログは全て英語のロケール設定で生成されたものを提示することを忘れないでください。例えば先頭に #{LC_ALL=C}# や +#{LC_ALL=en_US}# を付けて live-build コマンドを実行してください。 + +2~ 可能であれば失敗している状況を分離する + +可能であれば失敗している状況を可能な限りうまくいかなくなる最小の変更に分離してください。これは常に簡単だとは限らないので、報告の際にできないようであれば気にする必要はありません。しかし、開発サイクルを向上させたい場合、繰り返しのたびに変更する量を十分に小さくすると、実際の設定により近く、より単純な「ベース」設定を構成することによりうまくいかなくなる追加の変更点だけに問題を分離することができるかもしれません。どの変更によりうまくいかなくなっているのか区別するのに苦労している場合、それぞれの変更点が多すぎることが考えられ、その場合開発の進行は緩くなるはずです。 + +2~ 正しいパッケージに対してバグを報告する + +どの構成要素がそのバグの原因なのかわからない、あるいはそのバグが Live システム全般に関係するバグである場合は debian-live +疑似パッケージに対するバグとして報告してください。 + +とはいうものの、バグの現れ方を元にその範囲を限定してくれると助かります。 + +3~ ビルド時のパッケージ収集中 + +live-build は最初に /{debootstrap}/ で Debian +システムの基本的なパッケージを収集します。バグがここで起きていると思われる場合は、そのエラーが特定の Debian パッケージに +(ほとんどの場合こちらです) 関連するのか、パッケージ収集ツール自体に関連するものなのか確認してください。 + +どちらの場合でも、これは Live システムではなく Debian +自体のバグで、恐らく私達が直接修正することはできません。こういったバグはパッケージ収集ツールまたは失敗しているパッケージに対して報告してください。 + +3~ ビルド時のパッケージインストール中 + +live-build は追加のパッケージを Debian アーカイブからインストールしているため、利用する Debian +ディストリビューションとその日のアーカイブの状態によっては失敗するかもしれません。バグがここで起きていると思われる場合は、そのエラーが通常のシステムで再現できるか確認してください。 + +通常のシステムで再現できる場合これは Live システムではなく Debian のバグです - 失敗しているパッケージに対して報告してください。Live +システムのビルドとは別に /{debootstrap}/ を実行、あるいは #{lbbootstrap --debug}# +を実行するとさらなる情報を得られるでしょう。 + +また、ローカルミラーやプロキシの類を使っていて問題が起きている場合はまず、公式ミラーからパッケージを収集した場合に再現するか常に確認してください。 + +3~ ブート時 + +イメージがブートしない場合は{情報収集}#collect-information +で指定している情報を添えてメーリングリストに報告してください。そのイメージが正確にどのように/どの段階で失敗しているのか、仮想化を使っているのか実際のハードウェアなのか、ということについて忘れずに言及してください。何らかの仮想化技術を使っている場合はバグを報告する前に常に実際のハードウェアで実行してください。失敗しているときのスクリーンショットを提供することも、とても参考になります。 + +3~ 実行時 + +パッケージのインストールには成功したけれども Live システムを実際に実行している間に何か失敗している場合、これは恐らく Live +システムのバグです。その場合: + +2~ 調査してください + +バグを報告する前に、問題の症状やそのエラーメッセージについてウェブを検索してください。その問題に遭っているのがあなた一人だけだという可能性は非常に低いからです。他のどこかで議題に上り、解決できそうな方法やパッチ、回避策が提案されている可能性は常にあります。 + +Live +システムのメーリングリストや同様にホームページには。最新の情報がある可能性があるので、特に注意を払ってください。そういった情報が存在する場合は、バグ報告で常に参照するようにしてください。 + +さらに、似たことが既に報告されていないか live-build、live-boot、live-config、live-tools +の現在のバグ一覧を確認してください。 + +2~ バグの報告先 + +${project}ではバグ追跡システム (BTS) に報告されたバグを全て追跡しています。このシステムの使い方についての情報は +https://bugs.debian.org/ を見てください。#{reportbug}# +パッケージの同名コマンドを使ってバグを報告することもできます。 + +一般的に、ビルド時のエラーは live-build に、ブート時のエラーは live-boot に、実行時のエラーは live-config +パッケージに対して報告してください。どのパッケージが適切なのかよくわからない、あるいはバグの報告前にもっと支援が必要だという場合は +debian-live 疑似パッケージに対して報告してください。その場合は私達が調べて適切なものに割り当てし直します。 + +(Ubuntu その他の) Debian 派生ディストリビューションで見つかったバグは、それが公式の Debian パッケージを使っている Debian +システムでも再現するものでない限り、Debian BTS に報告すべきでは*{ない}*ことに注意してください。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/project_coding-style.ssi new file mode 100644 index 0000000..cc8c41a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/project_coding-style.ssi @@ -0,0 +1,140 @@ +:B~ コーディングスタイル + +1~coding-style コーディングスタイル + +この章では Live システムで利用されているコーディングスタイルについて述べます。 + +2~ 互換性 + +_* Bash シェル固有の書式や記号を使わないでください。例えば配列構造の利用など + +_* POSIX のサブセットだけを使ってください - 例えば `foo` よりも $(foo) を使ってください。 + +_* 'sh -n' と 'checkbashisms' によりスクリプトをチェックできます。 + +_* シェルコードが全て確実に 'set -e' で動作するようにしてください。 + +2~ インデント + +_* 常にスペースよりもタブを使います。 + +2~ 改行 + +_* 通常、行は最大で80文字までです。 + +_* 「Linux 式」で改行します: + +悪い例: + +code{ + + if foo; then + bar + fi + +}code + +良い例: + +code{ + + if foo + then + bar + fi + +}code + +_* 関数についても同様です: + +悪い例: + +code{ + + Foo () { + bar + } + +}code + +良い例: + +code{ + + Foo () + { + bar + } + +}code + +2~ 変数 + +_* 変数は常に大文字です。 + +_* live-build で利用する変数は先頭を常に #{LB_}# で始めます。 + +_* live-build 内部の一時変数は #{\_LB_}# で始めます。 + +_* live-build のローカル変数は #{\_\_LB_}# で始めます。 + +_* live-config 中のブートパラメータにつながる変数は #{LIVE_}# で始めます。 + +_* live-config 中の他の変数は全て #{_}# で始めます。 + +_* 変数は大括弧「{}」で囲みます。例えば #{$FOO}# ではなく #{${FOO}}# とします。 + +_* 空白文字の可能性を考慮し、常に引用符を使って変数を保護します: #{${FOO}}# ではなく #{"${FOO}"}# とします。 + +_* 一貫性を保つため、変数に値を割り当てるときは常に引用符を使います: + +悪い例: + +code{ + + FOO=bar + +}code + +良い例: + +code{ + + FOO="bar" + +}code + +_* 複数の変数を使うときは表現全体を引用符で囲みます: + +悪い例: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +良い例: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ その他 + +_* sed を呼び出すときは区切り文字に「#{|}#」を使います。例えば「#{sed -e 's|foo|bar|'}#」 + +_* 比較やテストには #{test}# コマンドを使わず、「#{[}#」や「#{]}#」を使います。例えば「#{if [ -x /bin/foo ]; +...}#」を使い、「#{if test -x /bin/foo; ...}#」は使いません。 + +_* #{test}# よりも #{case}# の方が読みやすく実行速度も早いため、可能な部分ではこちらを使います。 + +_* ユーザの環境と混ざる可能性を限定するため、関数の名前には大文字を使います。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/project_contributing.ssi new file mode 100644 index 0000000..a1dcea2 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/project_contributing.ssi @@ -0,0 +1,100 @@ +:B~ プロジェクトへの貢献 + +1~contributing-to-project プロジェクトへの貢献 + +貢献物の提出にあたっては著作権者を明確に識別し、適用するライセンス文を収録してください。受け入れられるためには、その貢献物はその文書の他の部分と同一の、GPL +バージョン 3 以降というライセンスを採用する必要があることに注意してください。 + +翻訳やパッチといったプロジェクトへの貢献は大いに歓迎します。誰もがリポジトリに直接コミットできますが、大きな変更についてはまずメーリングリストに送って議論するようお願いします。さらなる情報については{連絡先}#contact +節を見てください。 + +${project}ではGitをソースコード管理用のバージョン管理システムとして利用しています。{Gitリポジトリ}#git-repositories +で説明しているように、開発用ブランチは *{debian}* と *{debian-next}* の2つあります。debian-next ブランチの +live-boot、live-build、live-config、live-images、live-manual、live-tools +リポジトリには誰でもコミットできます。 + +ただし、特定の制限があります。サーバは + +_* fast-forward ではないプッシュ + +_* マージコミット + +_* タグやブランチの追加や削除 + +を拒否します。あらゆるコミットを訂正できるとはいえ、自分の常識に従って、良いコミットメッセージを使って良いコミットを行うようお願いします。 + +_* +完結した、有意な文で構成されるコミットメッセージを英語で書き、大文字から始めて句点で終えるようにしてください。通常、「Fixing/Adding/Removing/Correcting/Translating/...」のようなものから開始します。 + +_* 良いコミットメッセージを書いてください。先頭行はそのコミットの内容を正確にまとめるようにしてください。これは changelog +に収録されることになります。何か説明がさらに必要であれば、先頭行の後に1行空けてから書き、各段落の後には新たな空行を空けてください。段落の行の長さは80文字を超えないようにしてください。 + +_* +コミットは小分けにしてください。これは関係のないものをまとめてコミットしないようにということです。各変更ごとに別個にコミットするようにしてください。 + +2~ 変更を加える + +リポジトリに送るには、以下の手順に従う必要があります。ここでは live-manual +を例として使うのでそれは作業したいリポジトリに置き換えてください。live-manual +を変更する方法に関する詳細な情報については{この文書への貢献}#how-to-contribute を見てください。 + +_* 公開コミットキーを取得します: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* openssh-client の設定に以下を追記します: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* ssh 経由で live-manual の複製を取得します: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Gitで作者とメールをセットしたことを確認してください: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{重要:}* 変更はどれも *{debian-next}* ブランチにコミットする必要があるということを忘れないでください + +_* 変更を加えます。この例ではまずパッチの適用を扱う新しい節を書き、ファイルの追加をコミットする下準備をしてコミットメッセージを + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* のように書いてサーバにコミットを送ります: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/project_git.ssi new file mode 100644 index 0000000..91f84c6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/project_git.ssi @@ -0,0 +1,74 @@ +:B~ Gitリポジトリ + +1~git-repositories Gitリポジトリ + +${project}の利用可能な全リポジトリ一覧は http://live-systems.org/gitweb/ にあります。プロジェクトの git +URL は: #{プロトコル://live-systems.org/git/リポジトリ}# という形式になっています。したがって、live-manual +を読み込み専用で複製するには + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + + + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + + + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +のどれかを実行します。書き込み権限のある複製には #{git@live-systems.org:/リポジトリ}#という形式のアドレスを使います。 + +なので、繰り返しますが live-manual をssh経由で複製するには + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +と入力する必要があります。gitツリーは複数の異なるブランチでできています。*{debian}* 及び *{debian-next}* +ブランチは最終的には新しいリリースそれぞれに収録される実際の作業を収録しているため特に注目すべきです。 + +既存のリポジトリのどれかを複製した後は *{debian}* +ブランチにいるでしょう。これはプロジェクトの最新リリースの状態を確認するには適切ですが、作業開始前に必ず *{debian-next}* +ブランチに切り替える必要があります。切り替えには + +code{ + + $ git checkout debian-next + +}code + +を実行します。*{debian-next}* ブランチは常に fast-forward とは限らず、あらゆる変更が *{debian}* +ブランチにマージされる前にまずはこにコミットされます。例えて言えばテストの場のようなものです。このブランチで作業していてサーバにある変更を取得する必要がある場合は +#{git pull --rebase}# +を実行する必要があります。それにより、サーバから取得するときにローカルでの変更が反映され、その変更が最上位に配置されます。 + +2~ リポジトリを複数処理 + +Live システムのリポジトリを複数複製してすぐに、最新コードの確認、パッチ作成、あるいは翻訳での貢献等のために *{debian-next}* +ブランチに切り替えたい場合、複数のリポジトリを扱いやすくするための #{mrconfig}# +ファイルをgitサーバで提供していることを紫知っておくべきでしょう。これを使うには /{mr}/ パッケージをインストールする必要があります。その後、 + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +を実行します。このコマンドは自動的に複製し、プロジェクトにより作成される Debian パッケージの開発用リポジトリである +*{debian-next}* ブランチを取得します。これには、中でも live-images +リポジトリがあり、プロジェクトが一般用途向けに公開しているビルド済みイメージで利用される設定を収録しています。このリポジトリの使い方に関するさらなる情報については、{Git経由で公開されている設定の複製}#clone-configuration-via-git +を見てください。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/project_procedures.ssi new file mode 100644 index 0000000..2bca00e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/project_procedures.ssi @@ -0,0 +1,93 @@ +:B~ 手順 + +1~procedures 手順 + +この章では、Debian の他のチームと協調する必要のある、${project}の様々な作業の手順について触れます。 + +2~ 主要リリース + +Debian の安定版の新しい主要バージョンのリリースでは、その完成のために多くの異なるチームが協調して作業しています。どこかの時点で、Live +チームが参加して Live システムのイメージをビルドします。そのための要件は + +_* リリースしたバージョンに該当する debian 及び debian-security アーカイブを収録している、debian-live の +buildd からアクセスできるミラー + +_* イメージの名前は既知の形式である必要があります (例えば debian-live-バージョン-アーキテクチャ-収録デスクトップ環境等.iso)。 + +_* debian-cd から来るデータを同期する必要があります (udeb 除外一覧)。 + +_* ビルドされたイメージのミラーが cdimage.debian.org に置かれます。 + +2~ ポイントリリース + +_* ここでも、debian と debian-security の更新されたミラーが必要です。 + +_* ビルドされたイメージのミラーが cdimage.debian.org に置かれます。 + +_* 告知メールを送ります + +3~ ある Debian リリースの最後のポイントリリース + +ある Debian リリース向けの最後のイメージを ftp.debian.org から archive.debian.org +に移動した後にビルドするときには、chroot とバイナリミラーの両方を調整することを忘れないでください。そうすることで、古いビルド済み Live +イメージをユーザが変更しなくてもそのまま続けて使えるようになります。 + +3~ ポイントリリース告知用テンプレート + +ポイントリリース用の告知メールはテンプレートと以下のコマンドを使って生成できます。 + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +メールを送る前に注意深く確認し、他の人による校正を受けてください。 + +code{ + +Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [LIVE 固有の変更をここに] + * [LIVE 固有の変更をここに] + * [大きな問題については専用の節を作ることもあります] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_basics.ssi new file mode 100644 index 0000000..bffdaad --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_basics.ssi @@ -0,0 +1,520 @@ +:B~ 基本 + +1~the-basics 基本 + +この章ではビルドプロセスの概要と最も広く利用されている3種類のイメージの使用手順について簡単に述べます。最も汎用性の高い形式のイメージである +#{iso-hybrid}# +は、仮想マシンや光学メディア、USBポータブルストレージ機器上で利用できます。特に変わった状況では後述のように、#{hdd}# +形式の方が適するかもしれません。この章では #{netboot}# +形式のイメージをビルド、利用する手順を記載しています。この形式はサーバ上で必要とする準備のためにやや複雑になります。これは netboot +についてまだ不慣れな人にとってはわずかに高度な話題となりますが、その準備さえできればローカルネットワーク上でブートするためのイメージをテスト、展開するのに非常に便利な方法で、難なくイメージのメディアを扱うことができるため、ここに収録しています。 + +この節は {ウェブブート}#webbooting +の簡単な手引きで終えています。これは恐らく異なる目的の異なるイメージを必要に応じて切り替えて使う最も簡単な方法で、手段としてインターネットを使います。 + +この章全体を通して、live-build +により作成されるデフォルトのファイル名を頻繁に参照しています。{ビルド済みイメージをダウンロード}#downloading-prebuilt-images +した場合、実際のファイル名は異なる場合があります。 + +2~what-is-live Live システムとは何? + +Live システムとは、 通常 CD-ROM +やUSBメモリ等の取り外し可能メディア、あるいはネットワークからコンピュータ上でブートされるオペレーティングシステムを意味し、普通のドライブに何もインストールせずに利用でき、実行時に自動設定が行われます +({用語}#terms 参照)。 + +Live システムはオペレーティングシステムで、サポートしているうちの単一のアーキテクチャ (現在 amd64 と i386) +向けにビルドされています。以下から構成されています。 + +_* *{Linux カーネルイメージ}*、通常 #{vmlinuz*}# という名前です + +_* *{初期 RAM ディスクイメージ (initrd)}*: Linux ブート用に用意された RAM +ディスクで、システムのイメージをマウントするのに必要となる可能性があるモジュールとマウントするためのスクリプトをいくつか収録しています。 + +_* *{システムイメージ}*: オペレーティングシステムのファイルシステムのイメージです。通常、Live +システムのイメージサイズを最小限にするため、SquashFS +圧縮ファイルシステムが利用されています。このファイルシステムは読み込み専用であることに注意してください。そのため、ブート処理中は Live +システムはRAMディスクと「ユニオン」機構を利用して実行中のシステム中でファイルを書き込むことができるようにしています。ただし、オプションの保持機能を使っていない限り、変更は全てシャットダウンにより失われます +({保持機能}#persistence 参照)。 + +_* *{ブートローダ}*: +選択したメディアからブートするように作られた短いコードの集合で、オプション/設定を選択できるプロンプトやメニューを恐らく提示します。Linux +カーネルとその initrd +を読み込んでそのシステムのファイルシステム上で実行します。前に言及した構成要素を収録する対象メディアやファイルシステムの形式によっては別の方法があります。isolinux +では ISO9660 形式のCDやDVDからのブート、syslinux ではHDDやUSBドライブの VFAT +パーティションからのブート、extlinux では ext2/3/4 や btrfs パーティション、pxelinux では PXE +netboot、GRUB では ext2/3/4 パーティション、等。 + +live-build を使って Linux カーネル、initrd、それを実行するためのブートローダを独自仕様で用意して全て1つのメディア特有の形式 +(ISO9660 イメージやディスクイメージ等) でシステムのイメージをビルドできます。 + +2~downloading-prebuilt-images ビルド済みイメージのダウンロード + +このマニュアルの対象は自分の Live +イメージの開発やビルドですが、使い方の手引き、あるいは自分でビルドする代わりにビルド済みイメージを簡単に試してみたいこともあるでしょう。{live-images +のgitリポジトリ}#clone-configuration-via-git と公式の安定版 (stable) リリースを使ってビルドされたイメージが +https://www.debian.org/CD/live/ で公開されています。さらに、古いものや今後のリリース、non-free +ファームウェアを収録する非公式のイメージ、あるいはドライバが http://live-systems.org/cdimage/release/ +から利用できるようになっています。 + +2~using-web-builder ウェブ Live イメージビルダーの利用 + +コミュニティへのサービスとして、ウェブベースの Live イメージビルダーサービスを http://live-systems.org/build/ +で運営しています。このサイトはベストエフォートの方針で保守されています。つまり、最新でいつでも使える状態の維持に努め、大規模な運用停止については問題を告知しますが、100% +いつでも使えることやイメージの高速なビルドを保証することはできず、サービスについて解決に時間を要する問題が時々あるかもしれないということです。サービスについて問題や疑問があれば、問題のあるビルドへのリンクを添えて{連絡}#contact +してください。 + +3~ ウェブビルダーの使い方と注意 + +ウェブインターフェイスでは現在、オプションの不正な組み合わせを避ける対策を何も取っていません。また、特に、変更すると通常ウェブフォームにある他のオプションのデフォルト値 +(つまり live-build を直接使った場合の値) +が変わるオプションを変更した場合にウェブビルダーはそのデフォルト値を変更しません。最も顕著な例として、#{--architectures}# +をデフォルトの #{i386}# から #{amd64}# に変更すると対応するオプション #{--linux-flavours}# をデフォルトの +#{586}# から #{amd64}# に変更する必要があります。ウェブビルダーにインストールされている live-build +のバージョンやさらなる詳細については #{lb_config}# man ページを見てください。live-build +のバージョン番号はウェブビルダーのページ下部に記載されています。 + +ウェブビルダーにより提示される時間の推定は条件を考慮しない推定であり、実際にビルドにかかる時間を反映していないかもしれません。表示された後に更新もされません。それについては我慢してください。ビルド条件を送信した後にこのページを更新しないでください。更新すると同一のパラメータで再び新たにビルドを送信することになります。ビルドの通知をただの一度も受け取っておらず、十分な時間が確実に過ぎて、通知メールが自分の +spam メールフィルタに引っかかっていないことを確認した場合、{連絡}#contact してください。 + +ウェブビルダーがビルドできるイメージの種類は限定されています。これにより、利用や保守を簡単、能率的に維持できます。ウェブインターフェイスで提供されていない独自化を行いたい場合は、live-build +を使って自分のイメージをビルドする方法をこのマニュアルの残りで説明しています。 + +2~building-iso-hybrid 最初の段階: ISO hybrid イメージのビルド + +イメージの種類を問わず、イメージをビルドするのに同一の基礎手順を毎回実行する必要があります。最初の例ではビルド用のディレクトリを作成して、このディレクトリに移動してから +live-build コマンドを以下の順で実行し、X.org のないデフォルトの Live システムを収録する基本的な ISO hybrid +イメージを作成します。このイメージはCDやDVDメディアへの書き込み、さらにUSBメモリへの複製にも適しています。 + +作業ディレクトリの名前は完全に自由ですが、live-manual +全体で利用されている例を参考にする場合、特に異なる種類のイメージについて作業、実験している場合、各ディレクトリで作業しているイメージの識別を支援する名前を使うのは良い方法です。ここではデフォルトのシステムをビルドするとして、例えば +live-default と呼びましょう。 + +code{ + + $ mkdir live-default && cd live-default + +}code + +それから #{lb config}# コマンドを実行します。これにより他のコマンドが利用する「config/」階層を現在のディレクトリに作成します。 + +code{ + + $ lb config + +}code + +上記のコマンドにはパラメータが渡されていないので、様々な選択肢についてそれぞれのデフォルト値が使われます。さらなる詳細については {lb config +コマンド}#lb-config を見てください。 + +これで「config/」階層ができました。#{lb build}# コマンドでイメージをビルドします。 + +code{ + + # lb build + +}code + +コンピュータやネットワーク接続の速度により、このプロセスには少々時間がかかるかもしれません。完了すると、#{live-image-i386.hybrid.iso}# +イメージファイルが使える状態で現在のディレクトリにできているはずです。 + +*{注意:}* amd64 システムでビルドした場合は、出来上がるイメージの名前は #{live-image-amd64.hybrid.iso}# となります。マニュアル全体でこの慣例を採用していることに留意してください。 + +2~using-iso-hybrid ISO hybrid Live イメージの利用 + +ISO hybrid イメージをビルド、または https://www.debian.org/CD/live/ +にあるものをダウンロードした後、通常は次にブート用メディアとして CD-R(W) や DVD-R(W) の光学メディアかUSBメモリを用意します。 + +3~burning-iso-image ISOイメージの実際のメディアへの書き込み + +ISOイメージの書き込みは簡単です。/{xorriso}/ をインストールしてそれをコマンドラインから使ってイメージを書き込むだけです。例えば: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb ISO hybrid イメージのUSBメモリへのコピー + +#{xorriso}# で作られたISOイメージは #{cp}# +プログラムや同等プログラムを使って単純にUSBメモリにコピーすることができます。イメージファイルを置けるだけの十分に大きなサイズのUSBメモリを差し込んでそれがどのデバイスなのか決定します。以後 +#{${USBメモリ}}# として参照します。これは例えば #{/dev/sdb}# といったUSBメモリのデバイスファイルで、例えば +#{/dev/sdb1}# といったパーティションではありません! USBメモリを差し込んでから #{dmesg}# か、もっと良いのは #{ls -l +/dev/disk/by-id}# の出力を見ると正しいデバイス名を調べることができます。 + +正しいデバイス名を得られたことを確信できたら #{cp}# +コマンドを使ってイメージをUSBメモリにコピーします。*{これを実行すると以前そのUSBメモリにあった内容は全て確実に上書きされます!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBメモリ} + $ sync + +}code + +*{注意:}* /{sync}/ コマンドはイメージのコピー中にカーネルによりメモリに記憶されているデータが全てUSBメモリに書き込まれたことを保証するのに有用です。 + +3~using-usb-extra-space USBメモリの空きスペースの利用 + +#{live-image-i386.hybrid.iso}# をUSBメモリにコピーすると、最初のパーティションは Live +システムで埋められます。残った空きスペースを利用するには、/{gparted}/ や /{parted}/ +といったパーティション作業ツールを使ってそのUSBメモリに新しいパーティションを作成します。 + +code{ + + # gparted ${USBメモリ} + +}code + +パーティションの作成後にはファイルシステムを作成する必要があります。選択肢には ext4 等があります。#{${パーティション}}#には例えば +#{/dev/sdb2}# 等パーティションの名前が入ります。 + +code{ + + # mkfs.ext4 ${パーティション} + +}code + +*{注意:}* 余った容量を Windows で使いたい場合ですが、このOSでは最初のパーティション以外にアクセスすることは通常できません。この問題に対する解決策が{メーリングリスト}#contact でいくらか議論されていますが、簡単な解はないようです。 + +*{Remember: 新しい live-image-i386.hybrid.iso をUSBメモリにインストールする度に、パーティションテーブルがイメージの内容で上書きされるために USB メモリにあるデータは全て失われるので、追加パーティションをまずバックアップしてから、Live イメージの更新後に復帰させるようにしてください。}* + +3~booting-live-medium Live メディアのブート + +Live メディアCD、DVD、USBメモリ、あるいは PXE ブートでの初回ブート時に、そのコンピュータの BIOS +をまず設定する必要があるかもしれません。BIOS により機能やキーの割り当てが大きく異なるため、ここではそれについて深くは触れません。BIOS +によってはブートするデバイスのメニューをブート時に提示させるキー割り当てを提供しているものがあり、そのシステムでこれが利用できる場合は最も簡単な方法でしょう。それがない場合は +BIOS 設定メニューに入って Live システムのブートデバイスを通常のブートデバイスよりも前に配置するようにブート順を変更する必要があります。 + +メディアをブートするとブートメニューが表示されているでしょう。ここで単に enter を押すと、システムはデフォルトの項目 #{Live}# +とデフォルトのオプションを使ってブートします。ブートオプションのさらなる情報については、メニューの「ヘルプ」の項目や Live システム内にある +live-boot 及び live-config の man ページを見てください。 + +#{Live}# を選択してデフォルトのデスクトップ Live イメージをブートしたとして、ブートメッセージが流れた後、自動的に #{user}# +アカウントにログインし、デスクトップがすぐに使える状態で見えているはずです。{ビルド済みイメージ}#downloading-prebuilt-images +の #{standard}# 等コンソールだけのイメージをブートした場合はコンソールで自動的に #{user}# +アカウントにログインし、シェルプロンプトがすぐに使える状態で見えているはずです。 + +2~using-virtual-machine 仮想マシンを利用したテスト + +Live イメージを仮想マシン (VM) 内で実行すると開発の面で大きな時間の節約になるかもしれません。これには注意事項がないというわけではありません: + +_* VMの実行にはゲストOSとホストOSの両方に十分なRAMが必要で、CPUには仮想化をハードウェアでサポートしているものを推奨します。 + +_* VM上での実行には、例えばビデオ性能が低いこと、エミュレーするハードウェアの選択肢が限られていること等内在する制限がいくらかあります。 + +_* 特定のハードウェア向けの開発ではそのハードウェア自体での実行に代わるものはありません。 + +_* VMでの実行にのみ関連するバグが時々あります。その疑いがあるときはイメージをハードウェアで直接テストしてください。 + +こういった制約があることを理解した上で利用可能なVMソフトウェアを調べて要件に合うものを選択してください。 + +3~testing-iso-with-qemu QEMU でのISOイメージのテスト + +Debian で最も汎用性の高いVMは QEMU です。プロセッサが仮想化をハードウェアでサポートしている場合は /{qemu-kvm}/ +パッケージを使ってください。/{qemu-kvm}/ パッケージの説明に要件の簡単な一覧があります。 + +プロセッサがサポートしている場合はまず /{qemu-kvm}/ をインストールしてください。サポートしている場合は /{qemu}/ +をインストールしてください。以下の例ではどちらの場合もプログラム名は #{kvm}# ではなく #{qemu}# とします。/{qemu-utils}/ +パッケージもあると #{qemu-img}# で仮想ディスクのイメージを作成するのによいでしょう。 + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +ISOイメージのブートは簡単です: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +詳細については man ページを見てください。 + +3~testing-iso-with-virtualbox VirtualBox でのISOイメージのテスト + +/{virtualbox}/ でISOをテストするには: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +新しい仮想マシンを作成し、#{live-image-i386.hybrid.iso}# を CD/DVD +デバイスとして利用するようにストレージ設定を変更して仮想マシンを起動します。 + +*{注意:}* X.org を収録している Live システムを /{virtualbox}/ でテストしたい場合は live-build 設定に VirtualBox X.org ドライバパッケージ /{virtualboxbox-guest-dkms}/ 及び /{virtualboxbox-guest-x11}/ を収録するとよいでしょう。収録しない場合、解像度は 800x600 に限定されます。 + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +dkms +パッケージを機能させるためには、そのイメージで利用しているカーネルの種類のカーネルヘッダもインストールする必要があります。正しいパッケージの選択は上記で作成したパッケージ一覧に正しい +/{linux-headers}/ パッケージを手作業により列挙する代わりに live-build により自動的に行うことができます。 + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image HDDイメージのビルド及び利用 + +HDDイメージのビルドは全面的に ISO hybrid イメージのビルドと似ていて、#{-b hdd}# を指定することと出来上がりのファイル名が +#{live-image-i386.img}# +で光学メディアに書き込んで使うことができないという点が異なります。このイメージはUSBメモリやUSBハードドライブ、その他様々な他のポータブルストレージデバイスからのブートに適しています。通常、この目的には +ISO hybrid イメージを代わりに使えますが、BIOS が hybrid イメージを適切に処理できない場合はHDDイメージが必要となります。 + +*{注意:}* 前の例で ISO hybrid イメージを作成している場合 #{lb clean}# コマンド ({lb clean コマンド}#lb-clean 参照) で作業ディレクトリをきれいにする必要があります: + +code{ + + # lb clean --binary + +}code + +前と同様に #{lb config}# コマンドを実行します。今回はイメージの種類にHDDを指定する点が異なります: + +code{ + + $ lb config -b hdd + +}code + +それから #{lb build}# コマンドでイメージをビルドします: + +code{ + + # lb build + +}code + +ビルドが完了すると現在のディレクトリに #{live-image-i386.img}# ファイルができているはずです。 + +生成されたバイナリイメージには VFAT パーティションと syslinux +ブートローダが収録され、そのままUSB機器に書きこめます。繰り返しますがHDDイメージの使い方はUSBで ISO hybrid +イメージを使うのと同様です。{ISO hybrid Live イメージの利用}#using-iso-hybrid +の指示に従ってください。#{live-image-i386.hybrid.iso}# に代えて #{live-image-i386.img}# +をファイル名に使う点が異なります。 + +同様に、Qemu でHDDイメージをテストするには上記の {Qemu でのISOイメージのテスト}#testing-iso-with-qemu +で説明しているように /{qemu}/ をインストールしてください。それから #{kvm}# か #{qemu}# +のホストシステムで必要バージョンを実行し、最初のハードドライブとして #{live-image-i386.img}# を指定します。 + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image netboot イメージのビルド + +以下の順でコマンドを実行すると X.org のないデフォルトの Live システムを収録する基本的な netboot +イメージを作成します。ネットワーク越しのブートに適しています。 + +*{注意:}* 前に示した例からどれかを実行した場合、作業ディレクトリを #{lb clean}# コマンドできれいにする必要があります: + +code{ + + # lb clean + +}code + +この特定の場合必要な段階の掃除が #{lb clean --binary}# では不十分です。netboot イメージのビルドで live-build +が netboot の準備を自動的に実行するにあたって異なる initramfs 設定が必要なことがその原因です。initramfs の作成は +chroot の段階で行われるため、既存のビルドディレクトリで netboot に切り替えるということは chroot +の段階も再ビルドするということになります。したがって、#{lb clean}# (これは chroot の段階も削除します) を使う必要があります。 + +#{lb config}# コマンドを以下のように実行してイメージを netboot 用に設定します: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +ISO及びHDDイメージとは対照的に netboot +自体ではクライアントに対してファイルシステムのイメージを提供しないため、ファイルをNFS経由で提供する必要があります。lb config +で異なるネットワークファイルシステムを選択することもできます。#{--net-root-path}# 及び #{--net-root-server}# +オプションはそれぞれ、ブート時にファイルシステムのイメージが置かれるNFSサーバの位置とサーバを指定します。ネットワークやサーバに合う適切な値がセットされていることを確認してください。 + +それから #{lb build}# コマンドでイメージをビルドします: + +code{ + + # lb build + +}code + +ネットワーク経由のブートでは、クライアントは通常イーサネットカードの EPROM にある小さなソフトウェアを実行します。このプログラムは DHCP +リクエストを送り、IPアドレスと次に行うことについての情報を取得します。次の段階は通常、TFTP +プロトコルを経由した高レベルブートローダの取得です。これには pxelinux や GRUB、さらには直接 Linux +のようなオペレーティングシステムをブートすることもできます。 + +例えば生成された #{live-image-i386.netboot.tar}# アーカイブを #{/srv/debian-live}# +ディレクトリに展開すると、#{live/filesystem.squashfs}# にファイルシステムのイメージ、カーネルや +initrd、pxelinux ブートローダが #{tftpboot/}# にあることがわかるでしょう。 + +ネットワーク経由でのブートをできるようにするにはサーバ上でサービスを3つ、DHCP サーバ、TFTP サーバ、NFSサーバを設定する必要があります。 + +3~ DHCP サーバ + +ネットワーク経由でブートするクライアントシステムに対して確実にIPアドレスを1つ与え、PXEブートローダの位置を通知するようにネットワークの DHCP +サーバを設定する必要があります。 + +イメージしやすいように #{/etc/dhcp/dhcpd.conf}# 設定ファイルで設定する ISC DHCP サーバ +#{isc-dhcp-server}# 向けに書かれた例を示します: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ TFTP サーバ + +これはカーネルと初期RAMディスクをシステム実行時に提供します。 + +/{tftpd-hpa}/ パッケージをインストールすべきです。これはルートディレクトリ、通常 #{/srv/tftp}# +内にある全ファイルを提供できます。#{/srv/debian-live/tftpboot}# 内にあるファイルを提供させるには root で + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +を実行し、tftp サーバの新しいディレクトリについて聞かれたら回答します。 + +3~ NFSサーバ + +ゲストコンピュータが Linux カーネルをダウンロード、ブートして initrd を読み込むと、NFSサーバ経由で Live +ファイルシステムのイメージをマウントしようとします。 + +/{nfs-kernel-server}/ パッケージをインストールする必要があります。 + +それから #{/etc/exports}# に + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +のような行を追記してファイルシステムのイメージをNFS経由で利用できるようにし、この新しいエクスポートについてNFSサーバに知らせます: + +code{ + + # exportfs -rv + +}code + +この3つのサービスの設定にはやや注意が必要かもしれません。全て協調して機能させるまでには忍耐がいくらか必要かもしれません。さらなる情報については +http://www.syslinux.org/wiki/index.php/PXELINUX にある syslinux wiki や +http://d-i.alioth.debian.org/manual/ja.i386/ch04s05.html にある Debian +インストーラマニュアルの TFTP ネットブート節を見てください。方法はとても似ているので手助けになるかもしれません。 + +3~ ネットワーク経由のブートをテストする方法 + +Netboot イメージの作成は live-build +により簡単になりましたが、イメージを実際のマシンでテストするのは本当に時間がかかるものとなるかもしれません。 + +日常を楽にするために仮想化を利用できます。 + +3~ Qemu + +_* /{qemu}/、/{bridge-utils}/、/{sudo}/ をインストールします。 + +#{/etc/qemu-ifup}# を編集します: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +#{grub-floppy-netboot}# を取得またはビルドします。 + +「#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#」を引数にして #{qemu}# を実行します + +2~webbooting ウェブブート + +ウェブブートは手段としてインターネットを使い Live +システムをブートするための便利な方法です。ウェブブートの要件はとても少なくなっています。ある言い方をすれば必要なのはブートローダと初期RAMディスク、カーネルを収録したメディアです。別の言い方をすれば必要なのはファイルシステムを収録する +squashfs ファイルを置くウェブサーバです。 + +3~ ウェブブートファイルの取得 + +いつものように、イメージを自分でビルドすることも、プロジェクトのホームページ http://live-systems.org/ +から取得できるビルド済みファイルを利用することも可能です。自身の必要に応じて微調整ができるまでの初期テストにはビルド済みイメージの利用が手軽でしょう。Live +イメージのビルド後ならウェブブートに必要なファイルは #{binary/live/}# 下のビルドディレクトリで見つけられるでしょう。ファイルは +#{vmlinuz}#、#{initrd.img}#、#{filesystem.squashfs}# と呼ばれます。 + +必要なファイルを既に存在するISOイメージから抽出することも可能です。そのためには以下のようにしてそのイメージをループバックマウントします: + +code{ + + # mount -o loop image.iso /mnt + +}code + +ファイルは #{live/}# ディレクトリで見つけられます。この例の場合は #{/mnt/live/}# +になります。この方法にはそのイメージをマウントするのに root +になる必要があるという欠点があります。しかしこれには簡単に定型処理、つまり自動化できるという利点があります。 + +しかし疑いようもなく、ISOイメージからファイルを抽出すると同時にウェブサーバにアップロードするのに最も簡単なのはミッドナイトコマンダーや /{mc}/ +の利用でしょう。/{genisoimage}/ +パッケージをインストールしていれば2ペインのファイルマネージャによりISOファイルの内容を確認しながらもう1つのペインではftp経由でファイルをアップロードできます。この方法は手作業の介入が必要とはなりますが +root 権限を必要としません。 + +3~ ウェブブートイメージの起動 + +ユーザによってはウェブブートのテストに仮想化を好みますがここでは以下の活用事例に合わせて実際のハードウェアについて言及します。あくまで例だと思ってください。 + +ウェブブートイメージの起動は上記で示した構成要素、つまり #{vmlinuz}# と #{initrd.img}# をUSBメモリの #{live/}# +ディレクトリ以下に書き込み、ブートローダとして syslinux をインストールすれば十分です。そしてUSBメモリからブートしてブートオプションに +#{fetch=URL/ファイル/への/パス}# を入力します。live-boot は squashfs +ファイルを取得してRAMに格納します。こうして、ダウンロードした圧縮ファイルシステムを普通の Live システムとして使えるようになります。例えば: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{活用事例:}* ウェブサーバがあり、squashfs ファイルが2つ、1つは例えば gnome のようなデスクトップ環境一式を収録したものともう1つは標準のものが置かれているとします。あるマシンでグラフィカル環境が必要であればUSBメモリを差し込んで gnome 用イメージをウェブブートできます。後者のイメージに収録されている何かのツールが別のマシン等で必要になった場合は標準的なイメージをウェブブートできます。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-binary.ssi new file mode 100644 index 0000000..6ab1d9a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-binary.ssi @@ -0,0 +1,49 @@ +:B~ バイナリイメージの独自化 + +1~customizing-binary バイナリイメージの独自化 + +2~ ブートローダ + +live-build は /{syslinux}/ や (イメージの種類により) +その派生物の一部をブートローダとしてデフォルトで利用します。これは要件に合わせて簡単に独自化できます。 + +全面的なテーマを使うには #{/usr/share/live/build/bootloaders}# を #{config/bootloaders}# +にコピーしてその中のファイルを編集します。サポートしているブートローダ全部の設定変更を望まない場合は、ブートローダの1つ、例えば +#{config/bootloaders/isolinux}# にある *{isolinux}* +だけを局所的に地域化したものを提供するのでも、活用方法によりますが十分です。 + +のようになります。デフォルトのテーマを変更してブートメニューとともに表示される背景画像に個別のものを使いたい場合は 640x480 ピクセルの画像を +splash.png というファイル名で追加し、splash.svg ファイルを削除します。 + +変更を加えるに至る要因は多々あります。例えば syslinux +派生物ではデフォルトでタイムアウト時間が0に設定されていて、この場合はスプラッシュ画面でキーが押されるまでいつまでも一時停止状態で止まっているということになります。 + +デフォルトの #{iso-hybrid}# イメージのブート時のタイムアウト時間を変更する方法は、デフォルトの *{isolinux.cfg}* +ファイルを編集して1/10秒単位でタイムアウト時間を指定するだけです。5秒後にブートするように *{isolinux.cfg}* を変更する場合は + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ ISO メタ情報 + +ISO9660 +バイナリイメージの作成時に以下のオプションを使って、テキストの様々なメタ情報をイメージに追加できます。これはイメージのバージョンや設定をブートせずに簡単に識別する手助けとなります。 + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: +これにはイメージ上に置かれる、アプリケーションの説明を記述します。最大長は128文字です。 + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: +これはイメージの作成者を説明し、通常連絡先の詳細をいくらか含めます。このオプションのデフォルト値は作成に利用した live-build +のバージョンで、後でデバッグするときに手がかりとなることを意図しています。最大長は128文字です。 + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: +これはイメージの発行者を説明し、通常連絡先の詳細をいくらか含めます。最大長は128文字です。 + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: これはイメージのボリュームIDを指定します。Windows や +Apple Mac OS 等一部のプラットフォームではユーザから見えるラベルとして利用されます。最大長は32文字です。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-contents.ssi new file mode 100644 index 0000000..510323a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-contents.ssi @@ -0,0 +1,114 @@ +:B~ 収録内容の独自化 + +1~customizing-contents 収録内容の独自化 + +この章では収録するパッケージを単に選択だけにとどまらない、微調整まで含めた Live システムの収録内容の独自化について説明します。インクルードにより +Live +システムイメージの任意のファイルを追加、置換できるようになり、フックによりビルド時及びブート時の異なる段階で任意のコマンドを実行できるようになり、preseed +が debconf の質問に対する回答を提供することでパッケージのインストール時に設定できるようになります。 + +2~includes Includes + +理想的なのは変更されていないパッケージにより提供されるファイルを Live +システムで完全に収録することではありますが、ファイルを使って内容をいくらか提供あるいは変更することが便利なこともあります。インクルードを使うと Live +システムイメージ中の任意のファイルを追加 (または置換) することができるようになります。live-build +ではこれを使う仕組みを2つ提供しています: + +_* chroot ローカルインクルード: chroot/Live +ファイルシステムに対してファイルの追加や置換ができるようになります。さらなる情報については、{Live/chroot +ローカルインクルード}#live-chroot-local-includes を見てください。 + +_* バイナリローカルインクルード: +バイナリイメージ中のファイルの追加や置換ができるようになります。さらなる情報については、{バイナリローカルインクルード}#binary-local-includes +を見てください。 + +「Live」及び「バイナリ」イメージの違いについてのさらなる情報は、{用語}#terms を見てください。 + +3~live-chroot-local-includes Live/chroot ローカルインクルード + +chroot ローカルインクルードを使って chroot/Live ファイルシステム中のファイルの追加や置換を行い、それを Live +システムで利用することができます。代表的な使い方として Live システムで利用するユーザディレクトリ (#{/etc/skel}#) +の骨格を構成させ、live +ユーザのホームディレクトリを作成するということがあります。別の使い方としては設定ファイルを提供し、そのまま加工せずイメージ中に追加または置換するということがあります。加工が必要な場合は +{Live/chroot ローカルフック}#live-chroot-local-hooks を見てください。 + +ファイルを収録するには #{config/includes.chroot}# ディレクトリに単純に追加します。このディレクトリが Live +システムのルートディレクトリ #{/}# に対応します。例えば Live システムにファイル #{/var/www/index.html}# +を追加する場合: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +それから設定は以下の配置になっているでしょう: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +chroot +ローカルインクルードはパッケージがインストールされた後にインストールされるので、パッケージによりインストールされたファイルは上書きされます。 + +3~binary-local-includes バイナリローカルインクルード + +文書やビデオ等の内容をメディアのファイルシステムに収録して、メディアを差し込んで Live +システムをブートしなくてもすぐにアクセスできるようにするのにバイナリローカルインクルードを使えます。これは chroot +ローカルインクルードと同様の方法で動作します。例えばファイル #{~/video_demo.*}# が Live システムの実演ビデオで、リンク先の +HTML 索引ページでそれを説明しているものと仮定しましょう。単純に内容を #{config/includes.binary/}# にコピーします: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +これでファイルは Live メディアの最上位ディレクトリに現れます。 + +2~hooks フック + +フックではビルドの chroot 及び バイナリの段階でコマンドを実行し、イメージを独自化できます。 + +3~live-chroot-local-hooks Live/chroot ローカルフック + +chroot の段階でコマンドを実行するにはファイル名末尾が #{.hook.chroot}# でコマンドを収録するフックスクリプトを +#{config/hooks/}# ディレクトリに作成します。フックは残りの chroot 設定の適用後に chroot +内で実行されるため、フックの実行に必要なパッケージやファイルを全て確実に設定に収録することを忘れないようにしてください。代表的な chroot +の様々な独自化タスクについて #{/usr/share/doc/live-build/examples/hooks}# で提供されている chroot +フックスクリプトの例を確認してください。この例からコピーやシンボリックリンクを作成して自分の設定で使えます。 + +3~boot-time-hooks ブート時フック + +ブート時にコマンドを実行するために man ページの「独自化」節で説明されている live-config +フックを提供することができます。#{/lib/live/config/}# で提供している live-config +独自のフックを、実行順を示す頭の番号に注意して調べてください。それから自分のフックに実行順を示す適切な番号を頭に付けて、#{config/includes.chroot/lib/live/config/}# +内の chroot +ローカルインクルードか、{変更したあるいはサードパーティのパッケージのインストール}#installing-modified-or-third-party-packages +で説明している独自パッケージとして提供してください。 + +3~ バイナリローカルフック + +バイナリ段階でコマンドを実行するには、コマンドを収録するフックスクリプトを、末尾に #{.hook.binary}# を付けて +#{config/hooks/}# ディレクトリに作成します。このフックは他の binary_checksums +を除いたバイナリコマンドを全て実行した後の、バイナリコマンドのほぼ最後に実行されます。フック内のコマンドは chroot +内で実行されるのではないため、ビルドツリー外のファイルを変更することのないように注意してください。変更するとビルドシステムが機能しなくなるかもしれません! +代表的なバイナリ独自化タスクについて #{/usr/share/doc/live-build/examples/hooks}# +で提供されているバイナリフックスクリプトの例を確認してください。この例からコピーやシンボリックリンクを作成して自分の設定で使えます。 + +2~ Debconf 質問の preseed + +#{config/preseed/}# ディレクトリにある、末尾が段階 (#{.chroot}# か #{.binary}#) に続いて +#{.cfg}# で終わるファイルは debconf の preseed ファイルと見なされ、対応する段階で live-build により +#{debconf-set-selections}# を使ってインストールされます。 + +debconf のさらなる情報については、/{debconf}/ パッケージの #{debconf(7)}# を見てください。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-installer.ssi new file mode 100644 index 0000000..66d8e75 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-installer.ssi @@ -0,0 +1,69 @@ +:B~ Debian インストーラの独自化 + +1~customizing-installer Debian インストーラの独自化 + +Live システムのイメージは Debian +インストーラと統合できます。インストールには収録内容やインストーラの動作方法によりいくつもの異なる種類があります。 + +この節で「Debian インストーラ」と大文字を使った表記で参照しているところに注意してください - この表記の場合には公式の Debian +システム用インストーラを明示的に指していて、他の何かではありません。「d-i」と短縮することもよくあります。 + +2~ Debian インストーラの種類 + +インストーラの主な3つの種類: + +*{「通常の」Debian インストーラ}*: これは通常の Live システムのイメージで、(適切なブートローダからそれを選択した場合に) Debian のCDイメージをダウンロードしてそれをブートしたのと同様に標準の Debian インストーラを起動するための別個のカーネルと initrd を収録しています。Live システムとこういった別個の独立したインストーラを収録するイメージはよく「複合イメージ」と呼ばれます。 + +こういったイメージでは、/{debootstrap}/ を使ってローカルメディアやネットワークから .deb パッケージを取得、インストールすることで +Debian がインストールされます。結果としてはデフォルトの Debian システムがハードディスクにインストールされます。 + +このプロセス全体で、いくつもの方法で preseed を使って独自化できます。さらなる情報については Debian +インストーラマニュアルの関連するページを見てください。機能する preseed ファイルが得られたら live-build +が自動的にイメージに取り込んで使えるようになります。 + +*{「Live」Debian インストーラ}*: これは Live システムイメージで、(適切なブートローダからそれを選択した場合に) Debian インストーラを起動するための別個のカーネルと initrd を収録しています。 + +インストールは上記で説明した「通常の」インストールと全く同じように進みますが、実際にパッケージをインストールする段階で、/{debootstrap}/ +を使ってパッケージを取得、インストールする代わりに、Live ファイルシステムのイメージを対象にコピーします。これは live-installer +という特別な udeb により行っています。 + +この段階の後は、Debian インストーラはインストールや、ブートローダやローカルユーザ等の設定を通常どおり続けます。 + +*{注意:}* 一つの Live メディアのブートローダの項目で通常のインストーラと Live インストーラの両方に対応するには、#{live-installer/enable=false}# という preseed により live-installer を無効化する必要があります。 + +*{「デスクトップ」Debian インストーラ}*: 収録する Debian インストーラの種類を問わず、デスクトップからアイコンをクリックすることで #{d-i}# を起動できます。状況によってはこちらの方がユーザからわかりやすいこともあります。これを使えるようにするには debian-installer-launcher パッケージを収録する必要があります。 + +live-build は Debian インストーラのイメージをデフォルトではイメージに収録しないことに注意してください。#{lb config}# +により具体的に有効化する必要があります。さらに、「デスクトップ」インストーラが機能するようにするには Live +システムのカーネルが指定されたアーキテクチャで #{d-i}# が利用するカーネルと一致する必要があることに注意してください。例えば: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ preseed による Debian インストーラの独自化 + +https://www.debian.org/releases/stable/i386/apb.html にある Debian +インストーラマニュアルの付録Bで説明されていますが「preseed +は、インストールの実行中に手作業により回答を入力せずに、インストールプロセス中の質問の回答を設定する方法を提供します。これにより、ほとんどの方法のインストールを完全に自動化し、さらに通常のインストールでは利用できない特徴もあります」。この種の独自化は +live-build を使って設定を #{preseed.cfg}# ファイルに書き、#{config/includes.installer/}# +に置くことで最も完成させることができます。例えばロケールを #{en_US}# に設定する preseed は: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Debian インストーラの収録内容の独自化 + +実験やデバッグの目的で、ローカルでビルドした #{d-i}# の一部である udeb +パッケージを収録したいことがあるかもしれません。#{config/packages.binary/}# +にそれを配置してイメージに収録します。{Live/chroot ローカルインクルード}#live-chroot-local-includes +と同じ方法で内容を #{config/includes.installer/}# +に置くことで、追加または置換するファイルやディレクトリを同様にインストーラの initrd に収録することもできます。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-overview.ssi new file mode 100644 index 0000000..dee4093 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-overview.ssi @@ -0,0 +1,49 @@ +:B~ 収録内容の独自化 + +1~customization-overview 独自化の概要 + +この章では Live システムを独自化できる様々な方法について概要を示します。 + +2~ ビルド時とブート時の設定 + +Live +システムの設定オプションはビルド時に適用されるビルド時オプションとブート時に適用されるブート時オプションとに分けられます。ブート時オプションはさらに、live-boot +パッケージにより適用され、ブートの早い段階で起きるものと live-config +パッケージにより適用され、ブートの遅い段階で起きるものとに分けられます。ブート時オプションはどれも、ユーザがブートプロンプトで指定することで変更できます。イメージは、デフォルトのブートパラメータを指定してビルドし、デフォルト値を全て適応する場合オプションをユーザが何も指定せずに普通に +Live システムを直接ブートするようにもできます。特に、#{lb --bootappend-live}# +への引数は設定の維持やキーボードレイアウト、タイムゾーン等、Live +システムのカーネルコマンドラインオプションのデフォルト値で構成されます。例については{ロケールと言語の独自化}#customizing-locale-and-language +を見てください。 + +ビルド時設定オプションは #{lb config}# の man ページで説明されています。ブート時オプションは live-boot と +live-config の man ページで説明されています。live-boot 及び live-config パッケージはビルドする Live +システム内にインストールされますが、設定作業時に参照しやすいようにビルドシステムにもインストールすることを勧めます。収録されているスクリプトはどれも、そのシステムが +Live システムとして設定されていないと実行されないため、ビルドシステムへのインストールは安全です。 + +2~stages-of-the-build ビルド段階 + +ビルドプロセスは段階ごとに分けられ、様々な独自化がそれぞれ順に適用されます。実行の最初の段階は*{パッケージ収集}*段階です。この初期段階では +chroot ディレクトリを作成して Debian システムの骨子を構成するパッケージを集めます。引き続いて*{chroot}*段階があり、chroot +ディレクトリの構成を完了させ、他の内容とともに設定に列挙されているパッケージを全て収集します。収録内容の独自化はほとんどがこの段階で起こります。Live +イメージの準備の最終段階は*{バイナリ}*段階で、ブート可能なイメージをビルドします。chroot ディレクトリの内容を使って Live +システムのルートファイルシステムを作成し、インストーラと 対象メディアの Live +システムのファイルシステム外に配置する、他の追加の内容を全て収録します。Live イメージをビルドした後は、有効化されている場合はソースの tar +アーカイブを*{ソース}*段階で作成します。 + +各段階で、コマンドの適用には特定の順序があります。そのように配置することで、独自化を合理的に階層化できるようになります。例えば *{chroot}* +段階ではどのパッケージをインストールするよりも前に preseed +が適用され、ローカルに収録したどのファイルをコピーするよりも前にパッケージをインストールし、フックはその後に、収録内容を全て配置してから実行されます。 + +2~ ファイルによる lb config の補完 + +#{lb config}# は設定の骨格を #{config/}# ディレクトリに作成しますが、目標を実現するには #{config/}# +サブディレクトリ以下に追加のファイルを提供する必要があるかもしれません。設定のどこにファイルを置くかにより、Live +システムのファイルシステムやバイナリイメージのファイルシステムにコピーされるか、コマンドラインオプションとして渡す方法では扱いにくいビルド時のシステム設定を提供することになります。独自のパッケージ一覧やアートワーク、あるいはビルド時またはブート時に実行するフックスクリプト等を収録し、debian-live +は既にかなりの柔軟性がありますが、自身のコードでそれを後押しすることができます。 + +2~ 独自化タスク + +以下の章ではユーザがよく行う類の独自化タスクをほんの一部ですがまとめています: +{インストールするパッケージの独自化}#customizing-package-installation +{収録内容の独自化}#customizing-contents +{ロケールと言語の独自化}#customizing-locale-and-language diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-packages.ssi new file mode 100644 index 0000000..97c9ab5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-packages.ssi @@ -0,0 +1,510 @@ +:B~ インストールするパッケージの独自化 + +1~customizing-package-installation インストールするパッケージの独自化 + +恐らく Live システムの最も基本的な独自化はイメージに収録するパッケージの選択でしょう。この章では live-build +でのパッケージのインストールの独自化のためのビルド時の様々なオプションを見ていきます。イメージへのインストールに利用可能なパッケージに関して最も影響が大きい選択はディストリビューションとアーカイブ領域です。まともなダウンロード速度を確保するため、近いディストリビューションミラーを選択してください。backports +や experimental +あるいは独自のパッケージのある自身専用のリポジトリを追加することもできます。また、ファイルを直接パッケージとして収録することもできます。特定のデスクトップや言語のパッケージ等、多数の関連パッケージを同時にインストールするメタパッケージを含め、パッケージ一覧は定義できます。最後に、ビルドでパッケージをインストールするときに +/{apt}/ や好みにより /{aptitude}/ +を制御するオプションもいくらかあります。プロキシを使っていたり、推奨パッケージのインストールを無効にして容量を節約したい、インストールするパッケージのバージョンをAPTのピン経由で制御する必要がある、等便利だと思う場面があるかもしれません。 + +2~ パッケージソース + +3~ ディストリビューション、アーカイブ領域とモード + +ディストリビューションの選択は Live イメージへの収録に利用できるパッケージに最も影響があります。コード名を指定してください。${testing} +バージョンの live-build では ${testing} +がデフォルトになっています。現在アーカイブにある任意のディストリビューションをコード名で指定できます (詳細については{条件}#terms +参照)。#{--distribution}# +オプションはアーカイブ内のパッケージソースに影響するだけでなく、サポートしている各ディストリビューションをビルドするのに必要な動作をするよう +live-build に指示します。例えば*{unstable}*リリースであるsidに対してビルドする場合は: + +code{ + + $ lb config --distribution sid + +}code + +のように指定します。ディストリビューションアーカイブ内で、アーカイブ領域はアーカイブを大きく分類します。Debian +では#{main}#、#{contrib}#、#{non-free}# となっています。#{main}#に収録されるソフトウェアだけが Debian +ディストリビューションの一部であり、したがってそれがデフォルトとなっています。複数指定することもできます。例えば + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Debian 派生物によっては #{--mode}# オプションの実験的サポートが利用できるものがあります。このオプションは Debian +または未知のシステムでビルドしている場合にのみデフォルトで #{debian}# がセットされています。サポートしている派生物のどれかで #{lb +config}# を実行した場合のデフォルト値はその派生物のイメージを作成するための値になります。#{lb config}# を例えば +#{ubuntu}# モードで実行すると Debian +向けに代えて指定された派生物のディストリビューション名やアーカイブ領域がサポートされます。このモードはその派生物に合うように live-build +の挙動も変更します。 + +*{注意:}* モードを追加したプロジェクトの設定については主にそのオプションのサポートユーザの担当です。${project}は最善の努力をもって開発サポートを提供はしますが、私たちは派生物を自ら開発あるいはサポートしているわけではないため、あくまで派生物プロジェクトからのフィードバックが基になります。 + +3~ ディストリビューションミラー + +Debian +アーカイブは世界中の巨大なネットワークミラーにまたがって複製されているため、各地域の人が最高のダウンロード速度を求めて近いミラーを選択できます。#{--mirror-*}# +オプションはそれぞれ、ビルドの様々な段階でどのディストリビューションミラーを利用するのかを決定します。{ビルド段階}#stages-of-the-build +の繰り返しになりますが*{パッケージ収集}*段階は最小限のシステムで /{debootstrap}/ により最初に chroot +を構成する段階、*{chroot}* 段階は chroot を使って Live +システムのファイルシステムをビルドする段階です。ミラーはこの各段階ごとにそれぞれのオプションで指定するため*{バイナリ}*の段階では +#{--mirror-binary}# や #{--mirror-binary-security}# +の値が採用され、早い段階で使っていたミラーは置き換えられることになります。 + +3~distribution-mirrors-build-time ビルド時に利用するディストリビューションミラー + +ビルド時に利用するディストリビューションミラーにローカルミラーを指定するには、#{--mirror-bootstrap}# と +#{--mirror-chroot-security}# を以下のように指定するだけです。 + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +#{--mirror-chroot}# で指定する chroot ミラーのデフォルト値は #{--mirror-bootstrap}# +の値になっています。 + +3~ 実行時に利用するディストリビューションミラー + +#{--mirror-binary*}# オプションはバイナリイメージ中のディストリビューションミラーの位置を決定します。このオプションは Live +システムの実行中に追加のパッケージをインストールする際に利用できます。デフォルトは #{httpredir.debian.org}# +で、利用できるミラーの中から特にユーザのIPアドレスを基にして地理的に近いミラーを選択するサービスになっています。これはその Live +システムを利用するユーザにとって最適なミラーを予測できない場合に適切な選択です。以下の例に示すように自分専用の値を指定することもできます。この設定でビルドされたイメージはその"#{ミラー}#"が到達可能なネットワークにいるユーザにとってのみ適します。 + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories 追加リポジトリ + +リポジトリをさらに追加して、利用できるパッケージ選択の幅を対象ディストリビューション以外にも広げられます。それにより、例えば backports や +experimental、そして独自のパッケージを利用できます。追加のリポジトリを設定するには +#{config/archives/your-repository.list.chroot}# や +#{config/archives/your-repository.list.binary}# ファイルを作成します。#{--mirror-*}# +オプションにより、イメージのビルドの *{chroot}* 段階や*{バイナリ}*段階、つまり Live +システムの実行時に利用するリポジトリを決定できます。 + +例えば #{config/archives/live.list.chroot}# により Live システムのビルド時に debian-live +スナップショットリポジトリからパッケージをインストールできます。 + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +同一の行を #{config/archives/live.list.binary}# に追加すると、Live システムの +#{/etc/apt/sources.list.d/}# ディレクトリにそのリポジトリが追加されます。 + +こういったファイルが存在すれば自動的に処理されます。 + +リポジトリの署名に利用されたGPG鍵を #{config/archives/your-repository.key.{binary,chroot}}# +ファイルに置くこともできます。 + +APTのピン止めが独自に必要な場合、APT設定行等を +#{config/archives/your-repository.pref.{binary,chroot}}# ファイルに配置すれば自動的に Live +システムの #{/etc/apt/preferences.d/}# ディレクトリに追加されます。 + +2~choosing-packages-to-install インストールするパッケージの選択 + +There are a number of ways to choose which packages live-build will install +in your image, covering a variety of different needs. You can simply name +individual packages to install in a package list. You can also use +metapackages in those lists, or select them using package control file +fields. And finally, you may place package files in your #{config/}# tree, +which is well suited to testing of new or experimental packages before they +are available from a repository. + +3~package-lists パッケージ一覧 + +パッケージ一覧はインストールするパッケージを明確にする強力な方法です。一覧の構文では条件付けをサポートし、一覧の生成や複数の設定への適合を容易にしています。ビルド時にシェルヘルパーを使って一覧にパッケージ名を差し込むこともできます。 + +*{注意:}* 存在しないパッケージが指定されたときの live-build の挙動はAPTユーティリティの選択により決定されます。さらなる詳細については {apt と aptitude の選択}#choosing-apt-or-aptitude を見てください。 + +3~using-metapackages メタパッケージの利用 + +パッケージ一覧を指示するもっとも簡単な方法は利用するディストリビューションで保守されているタスクのメタパッケージの利用です。例えば: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +#{live-build}# 2.x +でサポートされていた、一覧を事前定義する古い方法はこれで置き換えられました。一覧の事前定義とは異なり、タスクのメタパッケージは Live +システムプロジェクト特有のものではありません。タスクのメタパッケージはディストリビューション内の専門の作業グループにより保守されているため、要求したユーザに対して提供する最善のパッケージについて、各グループでの合意を反映したものとなっています。また、一覧を事前定義する置き換えられた方法よりはるかに幅広い事例にも対応できます。 + +タスクのメタパッケージには全て先頭が #{task-}# から始まるため、利用できるものを簡単に判別する方法があります +(名前が該当しても実際にはメタパッケージではないものもほんの一部とはいえありますが)。パッケージ名を前方一致で検索します: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +以上に加え、他に様々な目的を持ったメタパッケージを見つけられるでしょう。#{gnome-core}# +のように他のもっと範囲の広いタスクパッケージの一部を構成するものや、#{education-*}# メタパッケージのように Debian Pure +Blend の中のある個々の専門分野に特化したものもあります。アーカイブにある全メタパッケージを列挙するには、#{debtags}# +パッケージをインストールして #{role::metapackage}# タグの付けられたパッケージを全て列挙させます: + +code{ + + $ debtags search role::metapackage + +}code + +3~ ローカルパッケージ一覧 + +列挙したものがメタパッケージであれ、個々のパッケージであれ、両方の組み合わせであれ、ローカルパッケージ一覧は全て +#{config/package-lists/}# +に保存されます。この一覧は複数利用できるため、うまい具合にこの一覧自体を組み込める設計になっています。例えばある一覧は特定のデスクトップ選択時向け、別の一覧は異なるデスクトップでも簡単に使えるような関連パッケージ群を、というようにできます。これにより、パッケージ群の異なる組み合わせを最小限の手間で試したり、あるいは異なる +Live イメージプロジェクトで一覧を共有する、といったことが可能になります。 + +このディレクトリに存在するパッケージ一覧は、処理対象とするためには後ろに #{.list}# +を付ける必要があり、さらにその一覧をどの段階の対象とするのか示すためには #{.chroot}# や #{.binary}# をその後に追加します。 + +*{注意:}* 対象とする段階の指定を追加しない場合、その一覧は両方の段階で利用されます。通常指定するのは #{.list.chroot}# で、この場合そのパッケージは Live ファイルシステムにのみインストールされ、メディア上に #{.deb}# の余計なコピーは置かれません。 + +3~ ローカルバイナリパッケージ一覧 + +バイナリ段階の一覧を作成する場合はファイルの末尾を #{.list.binary}# にして #{config/package-lists/}# +に置きます。それにより指定したパッケージは Live ファイルシステムにはインストールされず、Live メディアの #{pool/}# +以下に収録されます。Live ではないインストーラでこういった一覧を標準的に利用しているものもあります。バイナリ段階で chroot +段階と同一の一覧を利用したい場合は上述したように末尾を #{.list}# とします。 + +3~generated-package-lists 生成されたパッケージ一覧 + +一覧の構成はスクリプトで生成するのが最善の方法だということもあります。感嘆符から始まる行は全て、そのコマンドがイメージのビルド後に chroot +内で実行されることを示します。例えばパッケージ一覧に #{! grep-aptavail -n -sPackage -FPriority +standard | sort}# という行を書いておけば、#{Priority: standard}# +で利用可能なパッケージをソートした一覧を生成できます。 + +実際、パッケージの選択に #{grep-aptavail}# コマンド (#{dctrl-tools}# パッケージに収録) +はとても有用なので、#{live-build}# では便宜のため #{Packages}# +補助スクリプトを提供しています。このスクリプトは引数を#{フィールド}#と#{パターン}#の2つ取ります。一覧を作成する例: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ 条件付き内部パッケージ一覧の利用 + +#{config/*}# (#{LB_}# が先頭に付くものは除く) に保存された live-build +の設定変数はどれもパッケージ一覧の条件文で利用できます。一般には #{lb config}# +オプションを大文字に、ダッシュ文字をアンダースコアに変更したものになります。しかし実際に意味があるのは、パッケージ選択に関わるもの、例えば +#{DISTRIBUTION}# や #{ARCHITECTURES}#、#{ARCHIVE_AREAS}# だけです。 + +例えば #{--architectures amd64}# が指定された場合に #{ia32-libs}# をインストールする場合: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +任意の1つを条件の値とすることもできます。#{--architectures i386}# または #{--architectures amd64}# +のどちらかが指定された場合に /{memtest86+}/ をインストールする場合の例: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +値を複数指定できる変数を条件にすることもできます。#{--archive-areas}# で #{contrib}# または #{non-free}# +のどちらかが指定されている場合に /{vrms}/ をインストールする場合の例: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +入り組んだ条件分岐はサポートしていません。 + +% FIXME: + +3~ インストール時のパッケージの削除 + +#{config/package-lists}# ディレクトリの末尾が #{.list.chroot_live}# や +#{.list.chroot_install}# のファイルにパッケージを列挙できます。Live +用とインストール用の両方の一覧が存在する場合、#{.list.chroot_live}# に列挙されているパッケージは +(ユーザがインストーラを利用している場合) インストール後にフックにより削除されます。#{.list.chroot_install}# +に列挙されているパッケージは Live システムとインストールされたシステムの両方に存在することになります。これはインストーラ向けの特別な調整で、設定で +#{--debian-installer live}# をセットしている場合や Live +システム特有のパッケージをインストール時には削除したい場合に有用かもしれません。 + +3~desktop-and-language-tasks デスクトップ及び言語タスク + +デスクトップと言語のタスクは特別で、計画性や設定が追加で必要となります。Live イメージが Debian +インストーライメージとは異なる点です。Debian +インストーラでは、特定のデスクトップ環境向けに用意されたメディアでは対応するタスクは自動的にインストールされます。内部に +#{gnome-desktop}# や #{kde-desktop}#、#{lxde-desktop}#、#{xfce-desktop}# +タスクがあり、#{tasksel}# +のメニューにはどれも出てきません。同様に言語向けタスクのメニュー項目はありませんが、インストール中にユーザが選択した言語が対応する言語タスクの選択に影響します。 + +デスクトップ向け Live イメージ開発時には、イメージは通常動作するデスクトップを直接ブートし、デスクトップやデフォルト言語はどちらも Debian +インストーラの場合のように実行時に選択するのではなくビルド時に決められています。これは Live +イメージでデスクトップや言語を複数サポートしてユーザに選択の機会を与えるようにできないわけではなく、それが live-build +のデフォルトの挙動ではないというだけです。 + +言語特有のフォントや入力メソッドにどのパッケージを収録するのか、といった規定は言語タスクにはないので、特定のパッケージを収録したい場合は設定で指定する必要があります。ドイツ語サポートを収録した +GNOME デスクトップイメージの場合に収録するタスクのメタパッケージの例: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version カーネルのフレーバー (種類) とバージョン + +アーキテクチャによっては、イメージに複数のカーネルをデフォルトで収録することができます。フレーバーは #{--linux-flavours}# +オプションで選択できます。各フレーバーはデフォルトの短い #{linux-image}# +に、イメージに収録される実際のカーネルパッケージに依存する各メタパッケージの名前を付加した形式になります。 + +そうして、デフォルトで #{amd64}# アーキテクチャのイメージは #{linux-image-amd64}# +のメタパッケージを収録し、#{i386}# アーキテクチャのイメージは #{linux-image-586}# メタパッケージを収録します。 + +設定したアーカイブで複数バージョンのカーネルパッケージが利用できる場合、#{--linux-packages}# +オプションでカーネルパッケージ名の前半部を指定できます。例えば #{amd64}# アーキテクチャのイメージをビルドする際にテスト用に +experimental アーカイブを追加すると #{linux-image-3.18.0-trunk-amd64}# +カーネルをインストールできます。そのイメージの設定例: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels 独自のカーネル + +Debian パッケージ管理システムに組み入れられていれば、独自のカーネルを自分でビルド、収録できます。live-build システムは +#{.deb}# パッケージでビルドされていないカーネルはサポートしていません。 + +自身のカーネルパッケージを配置するための適切で推奨する方法は #{kernel-handbook}# +の指示に従うことです。パッケージ名のABIとフレーバーの部分を忘れずに適切に変更し、リポジトリに #{linux}# の完全なビルドとそれに該当する +#{linux-latest}# パッケージを収録してください。 + +該当するメタパッケージ無しでカーネルパッケージをビルドしたい場合は、{カーネルのフレーバー (種類) +とバージョン}#kernel-flavour-and-version で説明しているように #{--linux-packages}# +でパッケージ名の適切な前半部を指定する必要があります。{変更したあるいはサードパーティ製パッケージのインストール}#installing-modified-or-third-party-packages +で説明しているように、自身のリポジトリに独自のカーネルパッケージを収録する場合はそのようにするのが最善ですが、別の方法についても説明しています。 + +カーネルを独自化する方法はこの文書の対象範囲ではありません。とはいえ、設定が最低限満たさないといけない要件があります: + +_* 初期RAMディスクを利用する。 + +_* 結合ファイルシステムモジュール (つまり通常は #{aufs}#) を収録する。 + +_* 自分の設定で必要とする他のファイルシステムモジュール (つまり通常は #{squashfs}#) があればそれを収録する。 + +2~installing-modified-or-third-party-packages 変更したあるいはサードパーティ製パッケージのインストール + +Live システムの哲学には反しますが、Debian リポジトリにあるバージョンのパッケージを改変して Live +システムをビルドする必要に迫られることもあります。それは機能や言語、商標を変更あるいは追加するものであったり、既存のパッケージから望ましくない要素を削除するものであるかもしれません。同様に求める機能や独自開発の機能を追加するのに「サードパーティ製」パッケージを利用できます。 + +この節では変更したパッケージのビルドや保守については対象としていません。Joachim Breitner さんの +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +にある「How to fork privately」に書かれている方法が該当するのかもしれませんが。求める機能を収録したパッケージの作成については +https://www.debian.org/doc/maint-guide/ にある Debian 新メンテナーガイドその他で説明されています。 + +変更した独自のパッケージをインストールする方法は2つあります: + +_* #{packages.chroot}# + +_* 独自APTリポジトリの利用 + +#{packages.chroot}# +を使う方法はより簡単に出来て「一度限りの」独自化には有用ですが欠点がいくつかあります。一方独自のAPTリポジトリを使う方法はその準備に時間がかかりまます。 + +3~ #{packages.chroot}# を利用した独自のパッケージのインストール + +独自化したパッケージをインストールするには、単に#{config/packages.chroot/}# +ディレクトリにコピーします。このディレクトリ内に置かれたパッケージはビルドの際に Live システムに自動的にインストールされます - +他のどこかを指定する必要はありません。 + +パッケージ名は規定の命名規則に従わ*{ないといけません}*。それを簡単に行う方法は #{dpkg-name}# の利用です。 + +#{packages.chroot}# を利用した独自のパッケージのインストールには欠点があります: + +_* secure APT を利用することができません。 + +_* #{config/packages.chroot/}# ディレクトリに適切なパッケージを全てインストールしないといけません。 + +_* Live システムの設定をリビジョン管理するには適しません。 + +3~ APTリポジトリを利用した独自パッケージのインストール + +#{packages.chroot}# +を使う場合とは異なり、独自のAPTリポジトリを使う場合は他のどこかでパッケージを指定する必要があります。詳細については{インストールするパッケージの選択}#choosing-packages-to-install +を見てください。 + +独自のパッケージをインストールするためにAPTリポジトリを作成するのは不要な手間だと思うかもしれませんが、その基盤は変更したパッケージを後で更新する際に簡単に再利用できます。 + +3~ 独自パッケージとAPT + +live-build は Live +システムへのパッケージのインストールに全てAPTを利用するため、そのプログラムの挙動を引き継ぎます。関連する一例としては +(デフォルト設定だと仮定して)、異なる2つのリポジトリでバージョン番号の異なるあるパッケージが利用可能な場合に、APTはバージョン番号の大きい方のパッケージをインストールに選択します。 + +そのため、独自パッケージの #{debian/changeLog}# ファイルでバージョン番号を増加させ、公式の Debian +リポジトリにあるものよりも変更したバージョンが確実にインストールされるようにすると良いでしょう。Live +システムのAPTのピン設定を改変する方法もあります - さらなる情報については、{APTのピン止め}#apt-pinning を見てください。 + +2~ ビルド時のAPT設定 + +ビルド時だけに適用されるオプションを使ってAPTを設定できます (実行中の Live システムで利用されるAPTの設定は Live +システムの内容による通常の、#{config/includes.chroot/}# で適切な設定を収録する) +方法により設定できます。オプションの全容については #{lb_config}# man ページの #{apt}# で始まるオプションを見てください。 + +3~choosing-apt-or-aptitude apt と aptitude の選択 + +ビルド時にパッケージをインストールする際に /{apt}/ と /{aptitude}/ のどちらを利用するのか選択できます。利用するユーティリティは +#{lb config}# の #{--apt}# +引数で決定します。パッケージが欠けている場合の処理方法に顕著な違いがあることに着目し、パッケージのインストール時に望ましい挙動を実装している方を選択してください。 + +_* #{apt}#: この方法では、欠けているパッケージが指定された場合にそのパッケージのインストールは失敗します。これはデフォルトの設定です。 + +_* #{aptitude}#: この方法では、欠けているパッケージが指定された場合にそのパッケージのインストールは成功します。 + +3~ APTでのプロキシの利用 + +よく要求されるAPTの設定として、プロキシの内側でのイメージのビルドへの対応があります。必要に応じて、#{--apt-ftp-proxy}# や +#{--apt-http-proxy}# オプションによりAPTプロキシを指定できます。例: + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space APTの調整による容量節約 + +イメージのメディアの容量をいくらか節約する必要があるかもしれません。その場合は以下に挙げるオプションを利用するといいかもしれません。 + +APTの索引をイメージに収録したくない場合は除外できます: + +code{ + + $ lb config --apt-indices false + +}code + +これは #{/etc/apt/sources.list}# 内の項目には影響せず、単に #{/var/lib/apt}# +に索引ファイルを収録するかどうかだけに影響します。その代わりに、Live システムでAPTを操作するためにはこの索引が必要なので、#{apt-cache +search}# や #{apt-get install}# を実行する前にユーザは例えば #{apt-get update}# +をまず実行して索引を作成しないといけません。 + +推奨パッケージのインストールによりイメージが肥大化しているような場合、以下で説明している影響を踏まえた上でAPTのデフォルトオプションを無効にできます: + +code{ + + $ lb config --apt-recommends false + +}code + +推奨パッケージを無効にした場合の最も重要な影響は、#{live-boot}# や #{live-config}# 自体が、ほとんどの Live +設定に利用している重要な機能を提供する一部のパッケージを推奨していることによるもので、例えば #{live-config}# が推奨し、Live +ユーザの作成に利用している #{user-setup}# +があります。ほぼ例外なく、パッケージ一覧に追加しないといけないパッケージが推奨パッケージの中にいくらかあります。追加しない場合は、イメージが期待通りに動作しないということになります。ビルドに収録されている各 +#{live-*}# パッケージの推奨パッケージを確認し、省略できると確信できない場合はパッケージ一覧に当該パッケージを追加するようにしてください。 + +あるパッケージの推奨パッケージをインストールしないことによるもっと一般的な影響は「異常なインストール状態でなければあるパッケージとともにあるはずの」(Debian +ポリシーマニュアル7.2節) Live +システムのユーザが実際に必要とする一部のパッケージが省略されているかもしれないということです。したがって、推奨パッケージのインストールを無効にした場合とのパッケージ一覧 +(#{lb build}# により生成される #{binary.packages}# ファイル参照) +の違いを確認して、欠けているパッケージの中にインストールしたいものがあれば一覧に収録することを推奨しています。推奨パッケージからほんの一部を除外したい場合は、推奨パッケージのインストールは有効なままにしておき、{APTのピン止め}#apt-pinning +で説明しているようにAPTのピン機能で、選択したパッケージについて負の優先度をセットしてインストールされないようにする方法があります。 + +3~ apt や aptitude へのオプションの受け渡し + +障害となるAPTの挙動を変更するための #{lb config}# オプションがない場合、#{--apt-options}# や +#{--aptitude-options}# により任意のオプションを選択したAPTツールに渡せます。詳細については #{apt}# や +#{aptitude}# の man +ページを見てください。どちらのオプションにも、優先設定に加えて保持しておく必要のあるデフォルト値があることに注意してください。そのため、例えば +#{snapshot.debian.org}# からテスト用に何か取得する場合に +#{Acquire::Check-Valid-Until=false}# を指定するとAPTは古いままの #{Release}# +ファイルを使い続けます。以下の例のように、デフォルト値 #{--yes}# の後に新しいオプションを付加します: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +このオプションを利用する場合は man +ページを確認して完全に理解するようにしてください。これはあくまで例であり、イメージをこの方法で設定するようにという助言だと解釈することのないようにしてください。このオプションは例えば +Live イメージの最終的なリリースには適しません。 + +#{apt.conf}# のオプションを利用するようなもっと複雑なAPT設定には代わりに #{config/apt/apt.conf}# +ファイルを作成すると良いでしょう。少数ですが、よく必要とされるオプションへの有用なショートカットがあります。他の #{apt-*}# +オプションについても参照してください。 + +3~apt-pinning APTのピン止め + +背景として、#{apt_preferences(5)}# man +ページをまず読んでください。APTのピン機能はビルド時用と実行時用に設定できます。前者については +#{config/archives/*.pref}#、#{config/archives/*.pref.chroot}#、#{config/apt/preferences}# +を、後者については #{config/includes.chroot/etc/apt/preferences}# を作成してください。 + +${testing} の Live システムをビルドするとしましょう。その場合に必要な Live パッケージは全て、ビルド時にバイナリイメージを sid +からインストールする必要があります。APTソースに sid を追加して、ピン機能で sid の Live +パッケージには高い優先度をセットし、他のパッケージには全てデフォルトよりも低い優先度をセットする必要があります。そうするとビルド時に望むパッケージだけを +sid からインストールし、他は全て対象システムのディストリビューションである ${testing} から取得します。以下によりその動作になります: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +別のパッケージにより推奨されたパッケージを望まない場合に、ピン機能で優先度に負の値をセットすることによりそのパッケージをインストールしないようにできます。#{config/package-lists/desktop.list.chroot}# +で #{task-lxde-desktop}# を使って LXDE イメージをビルドしていて、wifi +パスワードをキーリングに保存するかユーザに聞かないようにしたいと仮定しましょう。このメタパッケージは /{lxde-core}/ +に依存し、/{lxde-core}/ は /{gksu}/ を推奨し、/{gksu}/ は /{gnome-keyring}/ +を推奨しています。そこで、推奨された /{gnome-keyring}/ +パッケージを除外したい場合、#{config/apt/preferences}# に以下を追加することで除外できます: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-runtime.ssi new file mode 100644 index 0000000..43364f9 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_customization-runtime.ssi @@ -0,0 +1,368 @@ +:B~ 実行時の挙動の独自化 + +1~customizing-run-time-behaviours 実行時の挙動の独自化 + +実行時に行われる設定は全て live-config により行われます。ユーザが関心を持つであろう live-config +の最も一般的なオプションから一部を説明します。オプションの全容は live-config の man ページにあります。 + +2~ live ユーザの独自化 + +重要な検討事項が1つあり、live ユーザはブート時に live-boot により作成され、ビルド時に live-build +により作成されるのではないということです。この影響は {Live/chroot +ローカルインクルード}#live-chroot-local-includes で説明しているように、ビルドで live +ユーザに関連する内容が導入されるところだけにはとどまらず、live ユーザに関連するグループや権限にも影響します。 + +live-config を設定できる複数の方法で live ユーザの所属する追加のグループを指定できます。例えば live ユーザを #{fuse}# +グループに追加するには #{config/includes.chroot/etc/live/config/user-setup.conf}# ファイルに + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +を追加するかブートパラメータとして +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +と指定します。 + +デフォルトのユーザ名「user」やデフォルトのパスワード「live」を変更することもできます。何らかの理由で変更したい場合は以下のようにして簡単に変更できます: + +デフォルトのユーザ名を変更するには単に設定で指定します: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +デフォルトのパスワードを変更できる1つの方法は{ブート時フック}#boot-time-hooks で説明しているフックを使います。そのためには +#{/usr/share/doc/live-config/examples/hooks}# から「passwd」を使い、適当な名前 (例えば +2000-passwd) で保存してそれを #{config/includes.chroot/lib/live/config/}# に追加します。 + +2~customizing-locale-and-language ロケールと言語の独自化 + +Live システムがブートする際、2つの段階で言語が関わってきます: + +_* ロケール生成 + +_* キーボードの設定 + +Live システムをビルドする際のデフォルトのロケールは #{locales=en_US.UTF-8}# となっています。生成したいロケールの定義には +#{lb config}# の #{--bootappend-live}# オプションで #{locales}# パラメータを指定します。例えば + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +ロケールをコンマで区切って複数指定することもできます。 + +このパラメータも以下に示すキーボード設定用パラメータと同様にカーネルコマンドラインで指定できます。ロケールは #{言語_国}# +(デフォルトのエンコーディングを使う場合) または完全な #{言語_国.エンコーディング}# +の形式で指定できます。サポートしているロケールやそれぞれで利用されるエンコーディングの一覧は #{/usr/share/i18n/SUPPORTED}# +にあります。 + +コンソールとXキーボードの設定はどちらも #{live-config}# により #{console-setup}# +パッケージを使って行われます。設定には #{--bootappend-live}# オプション経由で +#{keyboard-layouts}#、#{keyboard-variants}#、#{keyboard-options}#、#{keyboard-model}# +ブートパラメータを利用します。それぞれの有効なオプションは #{/usr/share/X11/xkb/rules/base.lst}# +にあります。ある言語向けのレイアウトや配列を見つけるには、その言語の英語名やその言語が話されている国を検索してみてください。例: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +それぞれの配列の説明に、適合するレイアウトが示されていることに注意してください。 + +レイアウトだけを設定する必要があることはよくあります。例えばXで利用するドイツ語のロケールファイル及びスイスのドイツ語のキーボードレイアウトを利用する場合: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +非常に具体的な事例ですが他のパラメータを同時に指定することもできます。例えばフランス語のシステムを用意して TypeMatrix EZ-Reach +2030 USB キーボードで (Bepo と呼ばれる) フランス語用の Dvorak 配置を使う場合: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +値を1つだけ受け付ける #{keyboard-model}# は例外ですが、他の #{keyboard-*}# +オプションではそれぞれに値をコンマで区切って複数指定することもできます。#{XKBMODEL}# や +#{XKBLAYOUT}#、#{XKBVARIANT}#、#{XKBOPTIONS}# 変数の詳細や例については #{keyboard(5)}# man +ページを見てください。#{keyboard-variants}# に複数の値を指定した場合、1つずつ #{keyboard-layouts}# の値 +(#{setxkbmap(1)}# の #{-variant}# オプション参照) +との照合が行われます。空白の値も使えます。例えばデフォルトとして米国向けの QWERTY、それとは別に米国向けの +Dvorak、の2つの配列を指定する場合: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence 保持機能 + +典型的なライブCDというものは CD-ROM +等の読み取り専用メディアから起動するインストール済みシステムで、書き込みや変更は起動したホストハードウェアの再起動により消え去ります。 + +Live +システムはそれを一般化したものであり、CD以外のメディアもサポートしますが、デフォルトの挙動としては読み取り専用であり、そのシステムで実行時に行ったことは全てシャットダウンにより失われるものだと考えるべきです。 + +「保持機能」というのは、実行時にシステムに行ったことの一部あるいは全てを保存し、リブート後に引き継ぐための様々な策の共通の呼び名です。それが機能する仕組みを理解するためには、読み取り専用メディアからブート、実行している場合でもファイルやディレクトリへの変更が書き込み可能メディア、標準的にはRAMディスク +(tmpfs) に書かれ、RAMディスクのデータはリブート後には残らないのだ、ということを知っておくと良いでしょう。 + +このRAMディスクに保存されるデータは、ローカルストレージメディアやネットワーク共有、あるいはマルチセッションで (再)書き込み可能な CD/DVD +のセッション等の書き込み可能な保持用メディアに保存する必要があります。こういったメディアは Live +システムで様々な方法でサポートされています。また、特別なブートパラメータ #{persistence}# +をブート時に指定する必要があるということも重要です。 + +ブートパラメータ #{persistence}# がセットされている (と同時に #{nopersistence}# がセットされていない) +場合、保持用ボリューム用のローカルストレージメディア (例えばハードディスクやUSBドライブ) がブート中に調査されます。live-boot(7) +man +ページで説明している特定のブートパラメータを指定することにより、利用する保持用ボリュームの種類を制限できます。保持用ボリュームは以下のどれかになります: + +_* GPT名により識別されるパーティション + +_* ファイルシステムラベルにより識別されるファイルシステム + +_* 読み取り可能な任意のファイルシステム (異質のOSの NTFS パーティションも利用可) +の最上位に置かれている、ファイル名により識別されるイメージファイル + +オーバーレイ用のボリュームラベルは #{persistence}# でないといけません。さらにその最上位に、ボリュームの保持を完全に制御するのに利用する +#{persistence.conf}# +というファイルが置かれていない限り無視されます。これは言うに及ばず、リブート後に保持用ボリュームに保存する対象となるディレクトリを指定します。さらなる詳細については +{persistence.conf ファイル}#persistence-conf を見てください。 + +保持用に利用するボリュームを用意する方法についていくつか例を示します。これは例えばハードディスクやUSBメモリに例えば + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +により作成した ext4 パーティションを利用できます。{USBメモリの空きスペースの利用}#using-usb-extra-space +も見てください。 + +デバイスに既存のパーティションがある場合は以下に示すどれかによりラベルを変更するだけで準備は終わりです: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +保持用に利用する ext4 ベースのイメージファイルの作成例: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +イメージファイル作成後、例えば #{/usr}# を保持させる場合に、保存するのはディレクトリに対する変更だけで、#{/usr}# +の内容を丸ごと保存したいわけではない、という場合、「union」オプションを利用できます。イメージファイルがホームディレクトリに置かれている場合はハードドライブのファイルシステム最上位にコピーして +#{/mnt}# にマウントします: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +それから、内容を追加する #{persistence.conf}# ファイルを作成してイメージファイルのマウントを解除します。 + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +ブートパラメータ「persistence」を指定して Live メディアでリブートします。 + +3~persistence-conf persistence.conf ファイル + +#{persistence}# のラベルを付けられたボリュームは #{persistence.conf}# +ファイルを使って、任意のディレクトリを保持するように設定します。ボリュームのファイルシステム最上位に置かれているこのファイルは保持するディレクトリや方法を制御します。 + +独自のオーバーレイマウントの設定方法は persistence.conf(5) man +ページで詳細に説明されていますが、ほとんどの場合簡単な例で十分なはずです。/dev/sdb1 パーティションの ext4 +ファイルシステムにホームディレクトリとAPTキャッシュを保持させる場合: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +それからリブートします。最初のブート中に #{/home}# と #{/var/cache/apt}# +の内容が保持用ボリュームにコピーされ、以後のこのディレクトリへの変更は全て保持用ボリュームに残ります。#{persistence.conf}# +ファイルに列挙するパスには空白文字や特別なパス構成要素 #{.}# and #{..}# +を含めることは一切できないことに注意してください。また、#{/lib}# や #{/lib/live}# (はそのサブディレクトリを含めて)、#{/}# +は独自マウントを使って保持させることができません。この制約の回避策として、#{persistence.conf}# ファイルに #{/ union}# +を追加すると完全な保持を実現できます。 + +3~ 保持先を複数使いたい場合 + +複数の保存先を使う方法は複数あります。目的の明確な例として、複数のボリュームを同時に使う場合と1つだけを選択して使う場合を取り上げます。 + +異なる (個別の #{persistence.conf}# ファイルを利用する) +独自オーバーレイボリュームを複数同時に利用できますが、同一のディレクトリを保持させる設定のボリュームが複数ある場合はその中から1つだけが利用されます。ある2つのマウントが「入り組んでいる」(つまり他にマウントしたディレクトリ以下のサブディレクトリとしてマウントする) +ような場合には子孫側ディレクトリよりも前に親側ディレクトリがマウントされるため、他のマウントにより見えなくなるマウントは発生しません。入り組んでいる独自マウントが同一の +#{persistence.conf}# ファイルで指定されている場合は問題があります。そういった状況が実際に必要な場合の処理方法については +persistence.conf(5) man ページを見てください (ヒント: 通常は必要ありません)。 + +ありそうな事例: ユーザデータ、つまり #{/home}# とスーパーユーザのデータ、つまり #{/root}# を異なるパーティションに保存するため +#{persistence}# ラベルの付いたパーティションを2つ作成し、それぞれに #{persistence.conf}# +ファイルを1つはユーザのファイルを保存する最初のパーティション向けに #{# echo "/home" > +persistence.conf}#、もう1つはスーパーユーザのファイルを保存する2つ目のパーティション向けに #{# echo "/root" > +persistence.conf}# として作成します。最後に、ブートパラメータとして #{persistence}# を使います。 + +別の位置やテストのために例えば #{private}# と #{work}# のようにして同一の種類で複数の保持先が必要な場合、ブートパラメータ +#{persistence}# と合わせてブートパラメータ #{persistence-label}# +を使うと、複数でそれぞれ一意となる保持用メディアを使えるようになります。例として、ブラウザのブックマークその他の個人用データ用に #{private}# +のラベルを付けられた保持用パーティションを使いたい場合、ブートパラメータとして #{persistence}# +#{persistence-label=private}# を使います。そして文書や研究プロジェクトその他の仕事関係のデータ用にはブートパラメータとして +#{persistence}# #{persistence-label=work}# を使います。 + +各ボリューム #{private}# 及び #{work}# にはそれぞれ最上位に #{persistence.conf}# +ファイルが必要だということは重要ですので覚えておいてください。古い名前でこういったラベルを使う方法についてさらなる情報が live-boot man +ページにあります。 + +3~ 暗号化した保持先の利用 + +保持機能を使うことには重要なデータが漏洩する危険がいくらか存在します。特に保持するデータがUSBメモリや外付ハードドライブ等のポータブル機器に保存される場合は。そういった場合には暗号化が便利です。手順が多いために全体として複雑に見えるかもしれませんが、live-boot +で暗号化したパーティションを扱うのは実際には簡単です。サポートしている *{luks}* +という種類の暗号化を利用するためには、暗号化したパーティションを作成する側と暗号化した保持用パーティションを利用する Live システムの両方のマシンに +/{cryptsetup}/ をインストールする必要があります。 + +マシンへの /{cryptsetup}/ のインストール: + +code{ + + # apt-get install cryptsetup + +}code + +Live システムに /{cryptsetup}/ をインストールするには、パッケージ一覧に追加します: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +/{cryptsetup}/ を備えた Live +システムが出来たら、基本的に必要なのは新しいパーティションを作成して暗号化し、#{persistence}# と +#{persistence-encryption=luks}# +パラメータを指定してブートするだけです。既にこの段階を予測し、通常の手順に沿ったブートパラメータを追加してあります: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +暗号化についてよく理解していない人たちのために詳細を見て行きましょう。以下の例では #{/dev/sdc2}# +に対応するUSBメモリ上のパーティションを利用します。自分で使う際にはどのパーティションになるのか判断する必要があることに注意してください。 + +最初の段階はUSBメモリを接続してそれがどのデバイスになるのか判断することです。live-manual で推奨するデバイス一覧方法では #{ls -l +/dev/disk/by-id}# を使います。それから新しいパーティションを作成、さらにパスフレーズを使って暗号化します: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +仮想デバイスマッパーから luks パーティションを開きます。好きな名前を使ってください。ここでは例として *{live}* を使います: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +次の段階はファイルシステムを作成する前にデバイスをゼロで埋めることです: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +これでファイルシステムを作成する準備ができました。ラベル #{persistence}# +の指定を追加しているためこのデバイスはブート時に保持用としてマウントされるということに注意してください。 + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +準備を続けるにはデバイスをマウントする必要があります。例として #{/mnt}# にマウントします。 + +code{ + + # mount /dev/mapper/live /mnt + +}code + +そしてパーティション最上位に #{persistence.conf}# +ファイルを作成します。これは前に説明したように必ず必要です。{persistence.conf ファイル}#persistence-conf +を見てください。 + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +それからマウントポイントのマウントを解除します: + +code{ + + # umount /mnt + +}code + +オプションですがパーティションに追加したばかりのデータを安全にしておくと良いでしょう。デバイスを閉じます: + +code{ + + # cryptsetup luksClose live + +}code + +手順をまとめます。これまでに、暗号化を有効化した Live システムを作成しました。これは {ISO hybrid +イメージのUSBメモリへのコピー}#copying-iso-hybrid-to-usb +で説明しているようにUSBメモリにコピーできます。暗号化したパーティションも作成しました。これは同一のUSBメモリに置いて持ち運べます。保持先として利用する暗号化パーティションを設定しました。あと必要なのは +Live システムをブートするだけです。ブート時に live-boot +は保持用として利用する暗号化したパーティションのパスフレーズを質問し、マウントします。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_installation.ssi new file mode 100644 index 0000000..28b8c94 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_installation.ssi @@ -0,0 +1,159 @@ +:B~ インストール + +1~installation インストール + +2~requirements 要件 + +Live システムイメージのビルドにはわずかながらシステム要件があります: + +_* スーパーユーザ (root) 権限 + +_* 最新版の live-build + +_* /{bash}/ や /{dash}/ 等の POSIX に準拠したシェル + +_* /{debootstrap}/ + +_* Linux 2.6 以降。 + +Debian や Debian 派生ディストリビューションの利用は必須ではないことに注意してください - live-build +は上記の要件を満たすほぼありとあらゆるディストリビューションで動作します。 + +2~installing-live-build live-build のインストール + +live-build のインストールにはいくつか方法があります: + +_* Debian リポジトリから + +_* ソースから + +_* スナップショットから + +Debian を使っている場合に推奨するのは Debian リポジトリからの live-build のインストールです。 + +3~ Debian リポジトリから + +他のあらゆるパッケージと同様に、単に live-build をインストールします: + +code{ + + # apt-get install live-build + +}code + +3~ ソースから + +live-build はGitバージョン管理システムを使って開発されています。Debian ベースのシステムでは /{git}/ +パッケージで提供されています。最新のコードを取得するには + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +を実行します。Debian パッケージを自分でビルド、インストールすることもできます。 + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +を実行し、新しくできた #{.deb}# ファイルから対象のものをインストールします。例えば + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +システムに live-build を直接インストールすることもできます: + +code{ + + # make install + +}code + +アンインストールは: + +code{ + + # make uninstall + +}code + +3~ 「スナップショット」から + +live-build をソースからビルドあるいはインストールしたくない場合、スナップショットを利用できます。スナップショットは Git +の最新版から自動的にビルドされ、http://live-systems.org/debian/ から利用できるようになっています。 + +2~ live-boot と live-config のインストール + +*{注意:}* 独自の Live システムを作成するためにシステムに live-boot や live-config をインストールする必要はありません。インストールは無害で、参照目的で有用でもあります。文書だけを望む場合には /{live-boot-doc}/ や /{live-config-doc}/ パッケージを別々にインストールできるようになっています。 + +3~ Debian リポジトリから + +live-boot と live-config はどちらも、{live-build のインストール}#installing-live-build +にあるように Debian リポジトリから利用できるようになっています。 + +3~ ソースから + +gitから最新のソースを利用するには以下の処理を追ってください。{用語}#terms で触れている用語について必ずよく理解しておくようにしてください。 + +_* live-boot 及び live-config のソースの取得 + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +パッケージをソースからビルドする理由が独自化である場合は、独自化の詳細について live-boot や live-config の man +ページを参考にしてください。 + +_* live-boot 及び live-config の .deb ファイルのビルド + +ビルドは対象ディストリビューションまたは対象のプラットフォームを収録している chroot で行う必要があります: これはつまり、対象が +${testing} であれば ${testing} に対してビルドすべきだということです。 + +ビルドシステムとは異なるディストリビューションを対象とする live-boot をビルドする必要がある場合は /{pbuilder}/ や +/{sbuild}/ といった個人向けビルダーを使ってください。例えば ${testing} の Live イメージであれば live-boot を +${testing} の chroot +でビルドしてください。対象のディストリビューションがビルドシステムのディストリビューションと一致している場合はビルドシステムで直接 +(/{dpkg-dev}/ パッケージにより提供される) #{dpkg-buildpackage}# を使ってビルドできます: + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* 件の .deb ファイルの利用 + +live-boot と live-config は live-build +システムによりインストールされるため、ホストシステムでパッケージをインストールするだけでは十分ではありません: 生成された .deb +ファイルを他の独自パッケージと同じように扱う必要があります。ソースからビルドする目的は恐らく公式リリース前の短期間に新しいものをテストすることなので、{変更したあるいはサードパーティ製パッケージのインストール}#installing-modified-or-third-party-packages +に従って、関連するファイルを設定に一時的に収録するようにしてください。特に、どちらのパッケージも一般的な部分、文書、そしてバックエンドに分割されていることに注意してください。一般的な部分と設定に合うバックエンドをただ1つ、オプションで文書を収録してください。Live +イメージを現在のディレクトリでビルドし、前述のディレクトリに両方のパッケージの単一バージョンの .deb ファイルを全て生成したものと仮定して、以下の +bash コマンドでデフォルトのバックエンドを含めて関連するパッケージを全てコピーします: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ 「スナップショット」から + +live-build の設定ディレクトリで live-systems.org +のパッケージリポジトリをサードパーティリポジトリとして設定することで、live-build が自動的に live-boot と live-config +の最新のスナップショットを利用するようにできます。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_managing_a_configuration.ssi new file mode 100644 index 0000000..8cf9132 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_managing_a_configuration.ssi @@ -0,0 +1,110 @@ +:B~ 設定の管理 + +1~managing-a-configuration 設定の管理 + +この章では live-build ソフトウェアと Live イメージ自体の両方について、最初の作成から継続的な改訂、継続的なリリースを通して Live +設定を管理する方法を説明します。 + +2~ 設定変更への対応 + +Live 設定が最初の試行で全て上手くいくのはまれです。一度だけビルドするのならコマンドラインから #{lb config}# +オプションを渡すだけで済むかもしれませんが、満足のいくまでオプションを改訂してビルドを繰り返す方が標準的です。そうした変更を支援するには設定を確実に一貫した状態に保つ自動化スクリプトが必要となるでしょう。 + +3~ 自動化スクリプトを使う理由は? それは何をするもの? + +#{lb config}# コマンドに渡されたオプションはされている他の多数のオプションと共にデフォルト値として #{config/*}# +ファイルに保管されます。その後に #{lb config}# +を実行した場合最初のオプションを基にしてデフォルトのオプションはリセットされません。そのため、例えば #{--binary-images}# +に新しい値を指定して再び #{lb config}# +を実行した場合以前指定していた種類のイメージに依存しているオプションのデフォルト値は新しく指定した種類のイメージでは使えなくなるかもしれません。そのファイルが読み取りや変更の対象からも外れているかもしれません。これを使うと100以上のオプションの値を保管するため、実際に指定されたオプションを誰でも確認できます。最後に、#{lb +config}# を実行した後に live-build をアップグレードして、オプションの名前が変更されていた場合、#{config/*}# +には古いオプションが有効ではなくなった後に名付けられた変数も収録されます。 + +以上に挙げた理由により #{auto/*}# スクリプトにより楽が出来るようになります。このスクリプト群は #{lb config}# や #{lb +build}#、#{lb clean}# コマンドの単純なラッパーで、設定の管理を支援するように設計されています。#{auto/config}# +スクリプトは #{lb config}# コマンドと希望したオプションを全て保管し、#{auto/clean}# +スクリプトは設定用変数値を収録するファイルを削除し、#{auto/build}# スクリプトは各ビルドの #{build.log}# +を維持します。このスクリプト群はそれぞれ対応する #{lb}# +コマンドの実行時に自動的に実行されます。このスクリプト群を利用することで設定が見やすくなり、改訂を越えて内部的に一貫した状態が維持されます。また、更新された文書を読んだ後に +live-build をアップグレードすれば変更の必要があるオプションを識別、修正するのははるかに容易になるでしょう。 + +3~ 自動化スクリプトの使用例 + +便宜のため live-build +には例の自動化シェルスクリプトが付属していてコピーして編集できるようになっています。デフォルトの設定を新しく作成してから例をコピーしましょう: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +#{auto/config}# を編集して、希望に合わせてオプションを追加します。例えば: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +これで、#{lb config}# を使うたびに #{auto/config}# +がそのオプションを基にして設定をリセットします。オプションを変更したいときには #{lb config}# +に渡すのではなくこのファイルに書かれているものを編集します。#{lb clean}# を使うと #{auto/clean}# は +#{config/*}# ファイルを、ビルドした他のものとあわせて削除します。最後に、#{lb build}# を使うとビルド時のログは +#{auto/build}# により #{build.log}# に書かれます。 + +*{注意:}* ここで特別な #{noauto}# パラメータを使い、#{auto/config}# を別に呼び出すことのないようにして無限再帰を回避しています。編集時に不注意で削除することのないようにしてください。また、読みやすくするために上記の例で示したように #{lb config}# コマンドを複数行に分割する場合は次の行に続く各行末のバックスラッシュ (\) を忘れることのないようにしてください。 + +2~clone-configuration-via-git Git経由で公開されている設定の複製 + +#{lb config --config}# オプションを使って Live +システムの設定を収録しているGitリポジトリを複製します。${project}により保守されている設定を基にしたい場合は +http://live-systems.org/gitweb/ の #{Packages}# カテゴリーの #{live-images}# +という名前のリポジトリに目を通してみてください。このリポジトリには Live システムの +{ビルド済みイメージ}#downloading-prebuilt-images 用の設定を収録しています。 + +例えば標準的なイメージをビルドするには #{live-images}# リポジトリを使って + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +のようにし、必要に応じて #{auto/config}# やその他 #{config}# ツリーにあるものを必要なだけ編集します。例えば非公式の +non-free ビルド済みイメージは単純に #{--archive-areas "main contrib non-free"}# +を追加することで作成されます。 + +オプションとしてGit設定でショートカットを定義することもできます。#{${HOME}/.gitconfig}# に + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +を追加すると #{live-systems.org}# にあるgitリポジトリのアドレスを指定する必要があるところで #{lso:}# +を使えるようになります。さらにオプションで末尾の #{.git}# も省くと、この設定を使って新しいイメージの作成を始めるのはこれだけ簡単になります: + +code{ + + $ lb config --config lso:live-images + +}code + +#{live-images}# +リポジトリ全体を複製すると数種類のイメージの設定を取得します。最初のイメージが出来上がってから異なるイメージをビルドしたい場合は別のディレクトリに移動して繰り返し、必要に応じて変更を加えてください。 + +どの場合も、イメージのビルド #{lb build}# は毎回スーパーユーザで行う必要があることを覚えておいてください。 diff --git a/markup/pod-samples/pod/live-manual/media/text/ja/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ja/user_overview.ssi new file mode 100644 index 0000000..fb98939 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ja/user_overview.ssi @@ -0,0 +1,108 @@ +:B~ ツールの概要 + +1~overview-of-tools ツールの概要 + +この章では Live システムのビルドに使う3つの主要ツール live-build、live-boot、live-config の概要をまとめています。 + +2~live-build live-build パッケージ + +live-build は Live システムをビルドするためのスクリプト集です。収録されているスクリプトは「コマンド」としても言及されています。 + +live-build の背景となる考え方は、設定ディレクトリを使って Live +イメージのビルドに関するあらゆる面を完全に自動化、独自化するフレームワークにしようということです。 + +その多くの概念は /{debhelper}/ で Debian パッケージをビルドするのと同様です: + +_* スクリプトには操作を制御するために中心となる位置があります。/{debhelper}/ ではパッケージツリーの #{debian/}# +サブディレクトリがこれにあたります。例えば dh_install は、他にもありますが、#{debian/install}# +というファイルを探して特定のバイナリパッケージに収録すべきファイルを判断します。ほぼ同様に live-build は設定全体を #{config/}# +サブディレクトリ以下に保管します。 + +_* スクリプトは独立しています - つまり、各コマンドの実行は常に安全です。 + +/{debhelper}/ とは異なり、live-build は設定ディレクトリの骨格を生成するツールを提供しています。これは /{dh-make}/ +等のツールに似ていると言っても良いでしょう。こういったツールのさらなる情報については、この節の残りで最も重要な4つのコマンドについて触れているので続きを読んでください。各コマンドで先行している +#{lb}# は live-build コマンドのラッパーであることに注意してください。 + +_* *{lb config}*: Live システム設定ディレクトリの初期化を担当します。さらなる情報については {lb config +コマンド}#lb-config を見てください。 + +_* *{lb build}*: Live システムのビルドの開始を担当します。さらなる情報については {lb build}#lb-build +を見てください。 + +_* *{lb clean}*: Live システムでビルドされた部分の掃除を担当します。さらなる情報については {lb clean +コマンド}#lb-clean を見てください。 + +3~lb-config #{lb config}# コマンド + +{live-build}#live-build で説明しているように、live-build を構成するスクリプトは #{config/}# +という名の単一のディレクトリから #{source}# +コマンドで指定された設定を読み込みます。このディレクトリを手作業により構成するのは時間がかかる上に誤りの元となりやすいため、#{lb config}# +コマンドを使って初期設定ツリーの骨格を作成できるようになっています。 + +引数を付けずに #{lb config}# を実行すると #{config/}# +サブディレクトリを作成してデフォルト設定がいくらか指定された設定ファイルを配置し、#{auto/}# 及び #{local/}# +という骨格となる2つのツリーを作成します。 + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +とても基本的なイメージを必要とするユーザや後で #{auto/config}# を使ってもっと全面的な設定を行おうと考えている場合は #{lb +config}# を引数無しで使うのが適切でしょう (詳細は{設定管理}#managing-a-configuration 参照)。 + +通常はオプションをいくらか指定します。例えばイメージのビルド時に利用するパッケージマネージャーを指定する場合: + +code{ + + $ lb config --apt aptitude + +}code + +多数のオプションを指定することもできます: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +利用可能なオプションの全容は #{lb_config}# man ページにあります。 + +3~lb-build #{lb build}# コマンド + +#{lb build}# コマンドは #{config/}# ディレクトリから設定を読み込みます。それから Live +システムのビルドに必要な低レベルコマンドを実行します。 + +3~lb-clean #{lb clean}# コマンド + +ビルドによる様々な生成物を削除するのは #{lb clean}# +コマンドの役目で、それによりその後のビルドがきれいな状態から始められるようになります。デフォルトで +#{chroot}#、#{バイナリ}#、#{ソース}#の段階が対象となりますが、キャッシュはそのまま残されます。また、個々の段階を個別に掃除することもできます。例えばバイナリ段階にのみ影響のある変更を加えた場合は新しいバイナリをビルドする前に +#{lb clean --binary}# を実行します。変更がパッケージ収集やパッケージのキャッシュを無効化するようなもの、例えば +#{--mode}# や #{--architecture}#、#{--bootstrap}# を変更した場合は #{lb clean +--purge}# を実行しないといけません。オプションの全容については #{lb_clean}# man ページを見てください。 + +2~live-boot live-boot パッケージ + +live-boot は live-build 等により作成される Live システムのブート時に利用する initramfs の生成に利用する +/{initramfs-tools}/ のフックを提供するスクリプト集です。Live +システムのISOやネットワーク経由のブートに利用するtarアーカイブ、USBメモリ向けイメージも対象です。 + +ブート時にはルートファイルシステム (squashfs のような圧縮ファイルシステムのイメージであることが多い) が保存されている #{/live/}# +ディレクトリを収録する読み取り専用メディアを探します。見つかった場合は Debian 類似システムでそのメディアからブートできるように、aufs +を使って書き込み可能な環境を作成します。 + +Debian の初期RAMファイルシステムについてのさらなる情報は http://kernel-handbook.alioth.debian.org/ +にある Debian Linux カーネルハンドブックの initramfs の章にあります。 + +2~live-config live-config パッケージ + +live-config はブート時に live-boot の後に実行して Live +システムを自動的に設定するためのスクリプト集で構成されています。ホスト名やロケール、タイムゾーンの設定や live ユーザの作成、cron +ジョブの抑制、live ユーザの自動ログイン等のタスクを処理します。 diff --git a/markup/pod-samples/pod/live-manual/media/text/lm_sdp1.txt b/markup/pod-samples/pod/live-manual/media/text/lm_sdp1.txt new file mode 100644 index 0000000..1762479 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/lm_sdp1.txt @@ -0,0 +1,2746 @@ +0 +------------------------------- +lib/sdp/ao_output_debugs.d:46 +[1][heading] +@title +[2][heading] +About +[3][heading] +About this manual +[4][heading] +About this manual +[5][para] +This manual serves as a single access point to all documentation related to the $${project} and in particular applies to the software produced by the project for the Debian 9.0 "$${stable}" release. An up-to-date version can always be found at http://live-systems.org/ +[6][para] +While live-manual is primarily focused on helping you build a live system and not on end-user topics, an end user may find some useful information in these sections: {The Basics}#the-basics covers downloading prebuilt images and preparing images to be booted from media or the network, either using the web builder or running live-build directly on your system. {Customizing run time behaviours}#customizing-run-time-behaviours describes some options that may be specified at the boot prompt, such as selecting a keyboard layout and locale, and using persistence. +[7][para] +Some of the commands mentioned in the text must be executed with superuser privileges which can be obtained by becoming the root user via #{su}# or by using #{sudo}#. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by #{$$}# or #{#}# respectively. This symbol is not a part of the command. +[8][heading] +For the impatient +[9][para] +While we believe that everything in this manual is important to at least some of our users, we realize it is a lot of material to cover and that you may wish to experience early success using the software before delving into the details. Therefore, we suggest reading in the following order. +[10][para] +First, read this chapter, {About this manual}#about-manual, from the beginning and ending with the {Terms}#terms section. Next, skip to the three tutorials at the front of the {Examples}#examples section designed to teach you image building and customization basics. Read {Using the examples}#using-the-examples first, followed by {Tutorial 1: A default image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these tutorials, you will have a taste of what can be done with live systems. +[11][para] +We encourage you to return to more in-depth study of the manual, perhaps next reading {The basics}#the-basics, skimming or skipping {Building a netboot image}#building-netboot-image, and finishing by reading the {Customization overview}#customization-overview and the chapters that follow it. By this point, we hope you are thoroughly excited by what can be done with live systems and motivated to read the rest of the manual, cover-to-cover. +[12][heading] +Terms +[13][para] +_* *{Live system}*: An operating system that can boot without installation to a hard drive. Live systems do not alter local operating system(s) or file(s) already installed on the computer hard drive unless instructed to do so. Live systems are typically booted from media such as CDs, DVDs or USB sticks. Some may also boot over the network (via netboot images, see {Building a netboot image}#building-netboot-image), and over the Internet (via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). +[14][para] +_* *{Live medium}*: As distinct from live system, the live medium refers to the CD, DVD or USB stick where the binary produced by live-build and used to boot the live system is written. More broadly, the term also refers to any place where this binary resides for the purposes of booting the live system, such as the location for the network boot files. +[15][para] +_* *{$${project}}*: The project which maintains, among others, the live-boot, live-build, live-config, live-tools and live-manual packages. +[16][para] +_* *{Host system}*: The environment used to create the live system. +[17][para] +_* *{Target system}*: The environment used to run the live system. +[18][para] +_* *{live-boot}*: A collection of scripts used to boot live systems. +[19][para] +_* *{live-build}*: A collection of scripts used to build customized live systems. +[20][para] +_* *{live-config}*: A collection of scripts used to configure a live system during the boot process. +[21][para] +_* *{live-tools}*: A collection of additional scripts used to perform useful tasks within a running live system. +[22][para] +_* *{live-manual}*: This document is maintained in a package called live-manual. +[23][para] +_* *{Debian Installer (d-i)}*: The official installation system for the Debian distribution. +[24][para] +_* *{Boot parameters}*: Parameters that can be entered at the bootloader prompt to influence the kernel or live-config. +[25][para] +_* *{chroot}*: The /{chroot}/ program, #{chroot(8)}#, enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting. +[26][para] +_* *{Binary image}*: A file containing the live system, such as live-image-i386.hybrid.iso or live-image-i386.img. +[27][para] +_* *{Target distribution}*: The distribution upon which your live system will be based. This can differ from the distribution of your host system. +[28][para] +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently codenamed $${stable}, contains the latest officially released distribution of Debian. The *{testing}* distribution, temporarily codenamed $${testing}, is the staging area for the next *{stable}* release. A major advantage of using this distribution is that it has more recent versions of software relative to the *{stable}* release. The *{unstable}* distribution, permanently codenamed sid, is where active development of Debian occurs. Generally, this distribution is run by developers and those who like to live on the edge. Throughout the manual, we tend to use codenames for the releases, such as $${testing} or sid, as that is what is supported by the tools themselves. +[29][heading] +Authors +[30][para] +A list of authors (in alphabetical order): +[31][para] +_* Ben Armstrong +[32][para] +_* Brendan Sleight +[33][para] +_* Carlos Zuferri +[34][para] +_* Chris Lamb +[35][para] +_* Daniel Baumann +[36][para] +_* Franklin Piat +[37][para] +_* Jonas Stein +[38][para] +_* Kai Hendry +[39][para] +_* Marco Amadori +[40][para] +_* Mathieu Geli +[41][para] +_* Matthias Kirschner +[42][para] +_* Richard Nelson +[43][para] +_* Trent W. Buck +[44][heading] +Contributing to this document +[45][para] +This manual is intended as a community project and all proposals for improvements and contributions are extremely welcome. Please see the section {Contributing to the project}#contributing-to-project for detailed information on how to fetch the commit key and make good commits. +[46][heading] +Applying changes +[47][para] +In order to make changes to the English manual you have to edit the right files in #{manual/en/}# but prior to the submission of your contribution, please preview your work. To preview the live-manual, ensure the packages needed for building it are installed by executing: +[48][code] + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + + +[49][para] +You may build the live-manual from the top level directory of your Git checkout by executing: +[50][code] + + $$ make build + + +[51][para] +Since it takes a while to build the manual in all supported languages, authors may find it convenient to use one of the fast proofing shortcuts when reviewing the new documentation they have added to the English manual. Using #{PROOF=1}# builds live-manual in html format, but without the segmented html files, and using #{PROOF=2}# builds live-manual in pdf format, but only the A4 and letter portraits. That is why using either of the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: +[52][code] + + $$ make build PROOF=1 + + +[53][para] +When proofing one of the translations it is possible to build only one language by executing, e.g: +[54][code] + + $$ make build LANGUAGES=de + + +[55][para] +It is also possible to build by document type, e.g: +[56][code] + + $$ make build FORMATS=pdf + + +[57][para] +Or combine both, e.g: +[58][code] + + $$ make build LANGUAGES=de FORMATS=html + + +[59][para] +After revising your work and making sure that everything is fine, do not use #{make commit}# unless you are updating translations in the commit, and in that case, do not mix changes to the English manual and translations in the same commit, but use separate commits for each. See the {Translation}#translation section for more details. +[60][heading] +Translation +[61][para] +In order to translate live-manual, follow these steps depending on whether you are starting a translation from scratch or continue working on an already existing one: +[62][para] +_* Start a new translation from scratch +[63][para] +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and *{index.html.in.pot}* files in #{manual/pot/}# to your language with your favourite editor (such as /{poedit}/) and send the translated #{.po}# files to the mailing list to check their integrity. live-manual's integrity check not only ensures that the #{.po}# files are 100% translated but it also detects possible errors. +[64][para] +_2* Once checked, to enable a new language in the autobuild it is enough to add the initial translated files to #{manual/po/$${LANGUAGE}/}# and run #{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the name of the language and its name in English between brackets. +[65][para] +_* Continue with an already started translation +[66][para] +_2* If your target language has already been added, you can randomly continue translating the remaining .po files in #{manual/po/$${LANGUAGE}/}# using your favourite editor (such as /{poedit}/). +[67][para] +_2* Do not forget that you need to run #{make commit}# to ensure that the translated manuals are updated from the .po files and then you can review your changes launching #{make build}# before #{git add .}#, #{git commit -m "Translating..."}# and #{git push}#. Remember that since #{make build}# can take a considerable amount of time, you can proofread languages individually as explained in {Applying changes}#applying-changes +[68][para] +After running #{make commit}# you will see some text scroll by. These are basically informative messages about the processing status and also some hints about what can be done in order to improve live-manual. Unless you see a fatal error, you usually can proceed and submit your contribution. +[69][para] +live-manual comes with two utilities that can greatly help translators to find untranslated and changed strings. The first one is "make translate". It launches an script that tells you in detail how many untranslated strings there are in each .po file. The second one, the "make fixfuzzy" target, only acts upon changed strings but it helps you to find and fix them one by one. +[70][para] +Keep in mind that even though these utilities might be really helpful to do translation work on the command line, the use of an specialized tool like /{poedit}/ is the recommended way to do the task. It is also a good idea to read the Debian localization (l10n) documentation and, specifically to live-manual, the {Guidelines for translators}#guidelines-translators. +[71][para] +*{Note:}* You can use #{make clean}# to clean your git tree before pushing. This step is not compulsory thanks to the .gitignore file but it is a good practice to avoid committing files involuntarily. +[72][heading] +About the $${project} +[73][heading] +About the $${project} +[74][heading] +Motivation +[75][heading] +What is wrong with current live systems +[76][para] +When $${project} was initiated, there were already several Debian based live systems available and they are doing a great job. From the Debian perspective most of them have one or more of the following disadvantages: +[77][para] +_* They are not Debian projects and therefore lack support from within Debian. +[78][para] +_* They mix different distributions, e.g. *{testing}* and *{unstable}*. +[79][para] +_* They support i386 only. +[80][para] +_* They modify the behaviour and/or appearance of packages by stripping them down to save space. +[81][para] +_* They include packages from outside of the Debian archive. +[82][para] +_* They ship custom kernels with additional patches that are not part of Debian. +[83][para] +_* They are large and slow due to their sheer size and thus not suitable for rescue issues. +[84][para] +_* They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images. +[85][heading] +Why create our own live system? +[86][para] +Debian is the Universal Operating System: Debian has a live system to show around and to accurately represent the Debian system with the following main advantages: +[87][para] +_* It is a subproject of Debian. +[88][para] +_* It reflects the (current) state of one distribution. +[89][para] +_* It runs on as many architectures as possible. +[90][para] +_* It consists of unchanged Debian packages only. +[91][para] +_* It does not contain any packages that are not in the Debian archive. +[92][para] +_* It uses an unaltered Debian kernel with no additional patches. +[93][heading] +Philosophy +[94][heading] +Only unchanged packages from Debian "main" +[95][para] +We will only use packages from the Debian repository in the "main" section. The non-free section is not part of Debian and therefore cannot be used for official live system images. +[96][para] +We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian. +[97][para] +As an exception, our own packages such as live-boot, live-build or live-config may temporarily be used from our own repository for development reasons (e.g. to create development snapshots). They will be uploaded to Debian on a regular basis. +[98][heading] +No package configuration of the live system +[99][para] +In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian. +[100][para] +Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian. +[101][para] +A system for configuring packages is provided using debconf allowing custom configured packages to be installed in your custom produced live system images, but for the {prebuilt live images}#downloading-prebuilt-images we choose to leave packages in their default configuration, unless absolutely necessary in order to work in the live environment. Wherever possible, we prefer to adapt packages within the Debian archive to work better in a live system versus making changes to the live toolchain or {prebuilt image configurations}#clone-configuration-via-git. For more information, please see {Customization overview}#customization-overview. +[102][heading] +Contact +[103][para] +_* *{Mailing list}*: The primary contact for the project is the mailing list at https://lists.debian.org/debian-live/. You can email the list directly by addressing your mail to debian-live@lists.debian.org. The list archives are available at https://lists.debian.org/debian-live/. +[104][para] +_* *{IRC}*: A number of users and developers are present in the #debian-live channel on irc.debian.org (OFTC). When asking a question on IRC, please be patient for an answer. If no answer is forthcoming, please email the mailing list. +[105][para] +_* *{BTS}*: The {Debian Bug Tracking System}https://www.debian.org/Bugs/ (BTS) contains details of bugs reported by users and developers. Each bug is given a number, and is kept on file until it is marked as having been dealt with. For more information, please see {Reporting bugs}#bugs. +[106][heading] +User +[107][heading] +Installation +[108][heading] +Installation +[109][heading] +Requirements +[110][para] +Building live system images has very few system requirements: +[111][para] +_* Superuser (root) access +[112][para] +_* An up-to-date version of live-build +[113][para] +_* A POSIX-compliant shell, such as /{bash}/ or /{dash}/ +[114][para] +_* /{debootstrap}/ +[115][para] +_* Linux 2.6 or newer. +[116][para] +Note that using Debian or a Debian-derived distribution is not required - live-build will run on almost any distribution with the above requirements. +[117][heading] +Installing live-build +[118][para] +You can install live-build in a number of different ways: +[119][para] +_* From the Debian repository +[120][para] +_* From source +[121][para] +_* From snapshots +[122][para] +If you are using Debian, the recommended way is to install live-build via the Debian repository. +[123][heading] +From the Debian repository +[124][para] +Simply install live-build like any other package: +[125][code] + + # apt-get install live-build + + +[126][heading] +From source +[127][para] +live-build is developed using the Git version control system. On Debian based systems, this is provided by the /{git}/ package. To check out the latest code, execute: +[128][code] + + $$ git clone git://live-systems.org/git/live-build.git + + +[129][para] +You can build and install your own Debian package by executing: +[130][code] + + $$ cd live-build + $$ dpkg-buildpackage -b -uc -us + $$ cd .. + + +[131][para] +Now install whichever of the freshly built #{.deb}# files you were interested in, e.g. +[132][code] + + # dpkg -i live-build_4.0-1_all.deb + + +[133][para] +You can also install live-build directly to your system by executing: +[134][code] + + # make install + + +[135][para] +and uninstall it with: +[136][code] + + # make uninstall + + +[137][heading] +From 'snapshots' +[138][para] +If you do not wish to build or install live-build from source, you can use snapshots. These are built automatically from the latest version in Git and are available on http://live-systems.org/debian/. +[139][heading] +Installing live-boot and live-config +[140][para] +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. +[141][heading] +From the Debian repository +[142][para] +Both live-boot and live-config are available from the Debian repository as per {Installing live-build}#installing-live-build. +[143][heading] +From source +[144][para] +To use the latest source from git, you can follow the process below. Please ensure you are familiar with the terms mentioned in {Terms}#terms. +[145][para] +_* Checkout the live-boot and live-config sources +[146][code] + + $$ git clone git://live-systems.org/git/live-boot.git + $$ git clone git://live-systems.org/git/live-config.git + + +[147][para] +Consult the live-boot and live-config man pages for details on customizing if that is your reason for building these packages from source. +[148][para] +_* Build live-boot and live-config .deb files +[149][para] +You must build either on your target distribution or in a chroot containing your target platform: this means if your target is $${testing} then you should build against $${testing}. +[150][para] +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to build live-boot for a target distribution that differs from your build system. For example, for $${testing} live images, build live-boot in a $${testing} chroot. If your target distribution happens to match your build system distribution, you may build directly on the build system using #{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): +[151][code] + + $$ cd live-boot + $$ dpkg-buildpackage -b -uc -us + $$ cd ../live-config + $$ dpkg-buildpackage -b -uc -us + + +[152][para] +_* Use applicable generated .deb files +[153][para] +As live-boot and live-config are installed by live-build system, installing the packages in the host system is not sufficient: you should treat the generated .deb files like any other custom packages. Since your purpose for building from source is likely to test new things over the short term before the official release, follow {Installing modified or third-party packages}#installing-modified-or-third-party-packages to temporarily include the relevant files in your configuration. In particular, notice that both packages are divided into a generic part, a documentation part and one or more back-ends. Include the generic part, only one back-end matching your configuration, and optionally the documentation. Assuming you are building a live image in the current directory and have generated all .deb files for a single version of both packages in the directory above, these bash commands would copy all of the relevant packages including default back-ends: +[154][code] + + $$ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $$ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + + +[155][heading] +From 'snapshots' +[156][para] +You can let live-build automatically use the latest snapshots of live-boot and live-config by configuring the package repository on live-systems.org as a third-party repository in your live-build configuration directory. +[157][heading] +The basics +[158][heading] +The basics +[159][para] +This chapter contains a brief overview of the build process and instructions for using the three most commonly used image types. The most versatile image type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or USB portable storage device. In certain special cases, as explained later, the #{hdd}# type may be more suitable. The chapter includes detailed instructions for building and using a #{netboot}# type image, which is a bit more involved due to the setup required on the server. This is an slightly advanced topic for anyone who is not already familiar with netbooting, but it is included here because once the setup is done, it is a very convenient way to test and deploy images for booting on the local network without the hassle of dealing with image media. +[160][para] +The section finishes with a quick introduction to {webbooting}#webbooting which is, perhaps, the easiest way of using different images for different purposes, switching from one to the other as needed using the internet as a means. +[161][para] +Throughout the chapter, we will often refer to the default filenames produced by live-build. If you are {downloading a prebuilt image}#downloading-prebuilt-images instead, the actual filenames may vary. +[162][heading] +What is a live system? +[163][para] +A live system usually means an operating system booted on a computer from a removable medium, such as a CD-ROM or USB stick, or from a network, ready to use without any installation on the usual drive(s), with auto-configuration done at run time (see {Terms}#terms). +[164][para] +With live systems, it's an operating system, built for one of the supported architectures (currently amd64 and i386). It is made from the following parts: +[165][para] +_* *{Linux kernel image}*, usually named #{vmlinuz*}# +[166][para] +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux boot, containing modules possibly needed to mount the System image and some scripts to do it. +[167][para] +_* *{System image}*: The operating system's filesystem image. Usually, a SquashFS compressed filesystem is used to minimize the live system image size. Note that it is read-only. So, during boot the live system will use a RAM disk and 'union' mechanism to enable writing files within the running system. However, all modifications will be lost upon shutdown unless optional persistence is used (see {Persistence}#persistence). +[168][para] +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen medium, possibly presenting a prompt or menu to allow selection of options/configuration. It loads the Linux kernel and its initrd to run with an associated system filesystem. Different solutions can be used, depending on the target medium and format of the filesystem containing the previously mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, extlinux for ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 partitions, etc. +[169][para] +You can use live-build to build the system image from your specifications, set up a Linux kernel, its initrd, and a bootloader to run them, all in one medium-dependant format (ISO9660 image, disk image, etc.). +[170][heading] +Downloading prebuilt images +[171][para] +While the focus of this manual is developing and building your own live images, you may simply wish to try one of our prebuilt images, either as an introduction to their use or instead of building your own. These images are built using our {live-images git repository}#clone-configuration-via-git and official stable releases are published at https://www.debian.org/CD/live/. In addition, older and upcoming releases, and unofficial images containing non-free firmware and drivers are available at http://live-systems.org/cdimage/release/. +[172][heading] +Using the web live image builder +[173][para] +As a service to the community, we run a web-based live image builder service at http://live-systems.org/build/. This site is maintained on a best effort basis. That is, although we strive to keep it up-to-date and operational at all times, and do issue notices for significant operational outages, we cannot guarantee 100% availability or fast image building, and the service may occasionally have issues that take some time to resolve. If you have problems or questions about the service, please {contact us}#contact, providing us with the link to your build. +[174][heading] +Web builder usage and caveats +[175][para] +The web interface currently makes no provision to prevent the use of invalid combinations of options, and in particular, where changing an option would normally (i.e. using live-build directly) change defaults of other options listed in the web form, the web builder does not change these defaults. Most notably, if you change #{--architectures}# from the default #{i386}# to #{amd64}#, you must change the corresponding option #{--linux-flavours}# from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for the version of live-build installed on the web builder for more details. The version number of live-build is listed at the bottom of the web builder page. +[176][para] +The time estimate given by the web builder is a crude estimate only and may not reflect how long your build actually takes. Nor is the estimate updated once it is displayed. Please be patient. Do not refresh the page you land on after submitting the build, as this will resubmit a new build with the same parameters. You should {contact us}#contact if you don't receive notification of your build only once you are certain you've waited long enough and verified the notification e-mail did not get caught by your own e-mail spam filter. +[177][para] +The web builder is limited in the kinds of images it can build. This keeps it simple and efficient to use and maintain. If you would like to make customizations that are not provided for by the web interface, the rest of this manual explains how to build your own images using live-build. +[178][heading] +First steps: building an ISO hybrid image +[179][para] +Regardless of the image type, you will need to perform the same basic steps to build an image each time. As a first example, create a build directory, change to that directory and then execute the following sequence of live-build commands to create a basic ISO hybrid image containing a default live system without X.org. It is suitable for burning to CD or DVD media, and also to copy onto a USB stick. +[180][para] +The name of the working directory is absolutely up to you, but if you take a look at the examples used throughout live-manual, it is a good idea to use a name that helps you identify the image you are working with in each directory, especially if you are working or experimenting with different image types. In this case you are going to build a default system so let's call it, for example, live-default. +[181][code] + + $$ mkdir live-default && cd live-default + + +[182][para] +Then, run the #{lb config}# command. This will create a "config/" hierarchy in the current directory for use by other commands: +[183][code] + + $$ lb config + + +[184][para] +No parameters are passed to these commands, so defaults for all of their various options will be used. See {The lb config command}#lb-config for more details. +[185][para] +Now that the "config/" hierarchy exists, build the image with the #{lb build}# command: +[186][code] + + # lb build + + +[187][para] +This process can take a while, depending on the speed of your computer and your network connection. When it is complete, there should be a #{live-image-i386.hybrid.iso}# image file, ready to use, in the current directory. +[188][para] +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. +[189][heading] +Using an ISO hybrid live image +[190][para] +After either building or downloading an ISO hybrid image, which can be obtained at https://www.debian.org/CD/live/, the usual next step is to prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or a USB stick. +[191][heading] +Burning an ISO image to a physical medium +[192][para] +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the command-line to burn the image. For instance: +[193][code] + + # apt-get install xorriso + $$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + + +[194][heading] +Copying an ISO hybrid image to a USB stick +[195][para] +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick with the #{cp}# program or an equivalent. Plug in a USB stick with a size large enough for your image file and determine which device it is, which we hereafter refer to as #{$${USBSTICK}}#. This is the device file of your key, such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find the right device name by looking in #{dmesg}#'s output after plugging in the stick, or better yet, #{ls -l /dev/disk/by-id}#. +[196][para] +Once you are certain you have the correct device name, use the #{cp}# command to copy the image to the stick.*{This will definitely overwrite any previous contents on your stick!}* +[197][code] + + $$ cp live-image-i386.hybrid.iso $${USBSTICK} + $$ sync + + +[198][para] +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. +[199][heading] +Using the space left on a USB stick +[200][para] +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first partition on the device will be filled up by the live system. To use the remaining free space, use a partitioning tool such as /{gparted}/ or /{parted}/ to create a new partition on the stick. +[201][code] + + # gparted $${USBSTICK} + + +[202][para] +After the partition is created, where #{$${PARTITION}}# is the name of the partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One possible choice would be ext4. +[203][code] + + # mkfs.ext4 $${PARTITION} + + +[204][para] +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. +[205][para] +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* +[206][heading] +Booting the live medium +[207][para] +The first time you boot your live medium, whether CD, DVD, USB key, or PXE boot, some setup in your computer's BIOS may be needed first. Since BIOSes vary greatly in features and key bindings, we cannot get into the topic in depth here. Some BIOSes provide a key to bring up a menu of boot devices at boot time, which is the easiest way if it is available on your system. Otherwise, you need to enter the BIOS configuration menu and change the boot order to place the boot device for the live system before your normal boot device. +[208][para] +Once you've booted the medium, you are presented with a boot menu. If you just press enter here, the system will boot using the default entry, #{Live}# and default options. For more information about boot options, see the "help" entry in the menu and also the live-boot and live-config man pages found within the live system. +[209][para] +Assuming you've selected #{Live}# and booted a default desktop live image, after the boot messages scroll by, you should be automatically logged into the #{user}# account and see a desktop, ready to use. If you have booted a console-only image, such as a #{standard}# flavour {prebuilt image}#downloading-prebuilt-images, you should be automatically logged in on the console to the #{user}# account and see a shell prompt, ready to use. +[210][heading] +Using a virtual machine for testing +[211][para] +It can be a great time-saver for the development of live images to run them in a virtual machine (VM). This is not without its caveats: +[212][para] +_* Running a VM requires enough RAM for both the guest OS and the host and a CPU with hardware support for virtualization is recommended. +[213][para] +_* There are some inherent limitations to running on a VM, e.g. poor video performance, limited choice of emulated hardware. +[214][para] +_* When developing for specific hardware, there is no substitute for running on the hardware itself. +[215][para] +_* Occasionally there are bugs that relate only to running in a VM. When in doubt, test your image directly on the hardware. +[216][para] +Provided you can work within these constraints, survey the available VM software and choose one that is suitable for your needs. +[217][heading] +Testing an ISO image with QEMU +[218][para] +The most versatile VM in Debian is QEMU. If your processor has hardware support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ package description briefly lists the requirements. +[219][para] +First, install /{qemu-kvm}/ if your processor supports it. If not, install /{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in the following examples. The /{qemu-utils}/ package is also valuable for creating virtual disk images with #{qemu-img}#. +[220][code] + + # apt-get install qemu-kvm qemu-utils + + +[221][para] +Booting an ISO image is simple: +[222][code] + + $$ kvm -cdrom live-image-i386.hybrid.iso + + +[223][para] +See the man pages for more details. +[224][heading] +Testing an ISO image with VirtualBox +[225][para] +In order to test the ISO with /{virtualbox}/: +[226][code] + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $$ virtualbox + + +[227][para] +Create a new virtual machine, change the storage settings to use #{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. +[228][para] +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. +[229][code] + + $$ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + + +[230][para] +In order to make the dkms package work, also the kernel headers for the kernel flavour used in your image need to be installed. Instead of manually listing the correct /{linux-headers}/ package in above created package list, the selection of the right package can be done automatically by live-build. +[231][code] + + $$ lb config --linux-packages "linux-image linux-headers" + + +[232][heading] +Building and using an HDD image +[233][para] +Building an HDD image is similar to an ISO hybrid one in all respects except you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# which cannot be burnt to optical media. It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices. Normally, an ISO hybrid image can be used for this purpose instead, but if you have a BIOS which does not handle hybrid images properly, you need an HDD image. +[234][para] +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): +[235][code] + + # lb clean --binary + + +[236][para] +Run the #{lb config}# command as before, except this time specifying the HDD image type: +[237][code] + + $$ lb config -b hdd + + +[238][para] +Now build the image with the #{lb build}# command: +[239][code] + + # lb build + + +[240][para] +When the build finishes, a #{live-image-i386.img}# file should be present in the current directory. +[241][para] +The generated binary image contains a VFAT partition and the syslinux bootloader, ready to be directly written on a USB device. Once again, using an HDD image is just like using an ISO hybrid one on USB. Follow the instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except use the filename #{live-image-i386.img}# instead of #{live-image-i386.hybrid.iso}#. +[242][para] +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run #{kvm}# or #{qemu}#, depending on which version your host system needs, specifying #{live-image-i386.img}# as the first hard drive. +[243][code] + + $$ kvm -hda live-image-i386.img + + +[244][heading] +Building a netboot image +[245][para] +The following sequence of commands will create a basic netboot image containing a default live system without X.org. It is suitable for booting over the network. +[246][para] +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: +[247][code] + + # lb clean + + +[248][para] +In this specific case, a #{lb clean --binary}# would not be enough to clean up the necessary stages. The cause for this is that in netboot setups, a different initramfs configuration needs to be used which live-build performs automatically when building netboot images. Since the initramfs creation belongs to the chroot stage, switching to netboot in an existing build directory means to rebuild the chroot stage too. Therefore, #{lb clean}# (which will remove the chroot stage, too) needs to be used. +[249][para] +Run the #{lb config}# command as follows to configure your image for netbooting: +[250][code] + + $$ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + + +[251][para] +In contrast with the ISO and HDD images, netbooting does not, itself, serve the filesystem image to the client, so the files must be served via NFS. Different network filesystems can be chosen through lb config. The #{--net-root-path}# and #{--net-root-server}# options specify the location and server, respectively, of the NFS server where the filesystem image will be located at boot time. Make sure these are set to suitable values for your network and server. +[252][para] +Now build the image with the #{lb build}# command: +[253][code] + + # lb build + + +[254][para] +In a network boot, the client runs a small piece of software which usually resides on the EPROM of the Ethernet card. This program sends a DHCP request to get an IP address and information about what to do next. Typically, the next step is getting a higher level bootloader via the TFTP protocol. That could be pxelinux, GRUB, or even boot directly to an operating system like Linux. +[255][para] +For example, if you unpack the generated #{live-image-i386.netboot.tar}# archive in the #{/srv/debian-live}# directory, you'll find the filesystem image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux bootloader in #{tftpboot/}#. +[256][para] +We must now configure three services on the server to enable netbooting: the DHCP server, the TFTP server and the NFS server. +[257][heading] +DHCP server +[258][para] +We must configure our network's DHCP server to be sure to give an IP address to the netbooting client system, and to advertise the location of the PXE bootloader. +[259][para] +Here is an example for inspiration, written for the ISC DHCP server #{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: +[260][code] + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + + +[261][heading] +TFTP server +[262][para] +This serves the kernel and initial ramdisk to the system at run time. +[263][para] +You should install the /{tftpd-hpa}/ package. It can serve all files contained inside a root directory, usually #{/srv/tftp}#. To let it serve files inside #{/srv/debian-live/tftpboot}#, run as root the following command: +[264][code] + + # dpkg-reconfigure -plow tftpd-hpa + + +[265][para] +and fill in the new tftp server directory when being asked about it. +[266][heading] +NFS server +[267][para] +Once the guest computer has downloaded and booted a Linux kernel and loaded its initrd, it will try to mount the Live filesystem image through a NFS server. +[268][para] +You need to install the /{nfs-kernel-server}/ package. +[269][para] +Then, make the filesystem image available through NFS by adding a line like the following to #{/etc/exports}#: +[270][code] + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + + +[271][para] +and tell the NFS server about this new export with the following command: +[272][code] + + # exportfs -rv + + +[273][para] +Setting up these three services can be a little tricky. You might need some patience to get all of them working together. For more information, see the syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the Debian Installer Manual's TFTP Net Booting section at http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, as their processes are very similar. +[274][heading] +Netboot testing HowTo +[275][para] +Netboot image creation is made easy with live-build, but testing the images on physical machines can be really time consuming. +[276][para] +To make our life easier, we can use virtualization. +[277][heading] +Qemu +[278][para] +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. +[279][para] +Edit #{/etc/qemu-ifup}#: +[280][code] + + #!/bin/sh + sudo -p "Password for $$0:" /sbin/ifconfig $$1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $$1 for bridged mode..." + sudo /sbin/ifconfig $$1 0.0.0.0 promisc up + echo "Adding $$1 to br0..." + sudo /usr/sbin/brctl addif br0 $$1 + sleep 2 + + +[281][para] +Get, or build a #{grub-floppy-netboot}#. +[282][para] +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" +[283][heading] +Webbooting +[284][para] +Webbooting is a convenient way of retrieving and booting live systems using the internet as a means. The requirements for webbooting are very few. On the one hand, you need a medium with a bootloader, an initial ramdisk and a kernel. On the other hand, a web server to store the squashfs files which contain the filesystem. +[285][heading] +Getting the webboot files +[286][para] +As usual, you can build the images yourself or use the prebuilt files, which are available on the project's homepage at http://live-systems.org/. Using prebuilt images would be handy for doing initial testing until one can fine tune their own needs. If you have built a live image you will find the files needed for webbooting in the build directory under #{binary/live/}#. The files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. +[287][para] +It is also possible to extract those files from an already existing iso image. In order to achieve that, loopback mount the image as follows: +[288][code] + + # mount -o loop image.iso /mnt + + +[289][para] +The files are to be found under the #{live/}# directory. In this specific case, it would be #{/mnt/live/}#. This method has the disadvantage that you need to be root to be able to mount the image. However, it has the advantage that it is easily scriptable and thus, easily automatized. +[290][para] +But undoubtedly, the easiest way of extracting the files from an iso image and uploading it to the web server at the same time, is using the midnight commander or /{mc}/. If you have the /{genisoimage}/ package installed, the two-pane file manager allows you to browse the contents of an iso file in one pane and upload the files via ftp in the other pane. Even though this method requires manual work, it does not require root privileges. +[291][heading] +Booting webboot images +[292][para] +While some users will prefer virtualization to test webbooting, we refer to real hardware here to match the following possible use case which should only be considered as an example. +[293][para] +In order to boot a webboot image it is enough to have the components mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a directory named #{live/}# and install syslinux as bootloader. Then boot from the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot options. live-boot will retrieve the squashfs file and store it into ram. This way, it is possible to use the downloaded compressed filesystem as a regular live system. For example: +[294][code] + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + + +[295][para] +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. +[296][heading] +Overview of tools +[297][heading] +Overview of tools +[298][para] +This chapter contains an overview of the three main tools used in building live systems: live-build, live-boot and live-config. +[299][heading] +The live-build package +[300][para] +live-build is a collection of scripts to build live systems. These scripts are also referred to as "commands". +[301][para] +The idea behind live-build is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image. +[302][para] +Many concepts are similar to those used to build Debian packages with /{debhelper}/: +[303][para] +_* The scripts have a central location for configuring their operation. In /{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For example, dh_install will look, among others, for a file called #{debian/install}# to determine which files should exist in a particular binary package. In much the same way, live-build stores its configuration entirely under a #{config/}# subdirectory. +[304][para] +_* The scripts are independent - that is to say, it is always safe to run each command. +[305][para] +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton configuration directory. This could be considered to be similar to tools such as /{dh-make}/. For more information about these tools, read on, since the remainder of this section discuses the four most important commands. Note that the preceding #{lb}# is a generic wrapper for live-build commands. +[306][para] +_* *{lb config}*: Responsible for initializing a Live system configuration directory. See {The lb config command}#lb-config for more information. +[307][para] +_* *{lb build}*: Responsible for starting a Live system build. See {The lb build command}#lb-build for more information. +[308][para] +_* *{lb clean}*: Responsible for removing parts of a Live system build. See {The lb clean command}#lb-clean for more information. +[309][heading] +The #{lb config}# command +[310][para] +As discussed in {live-build}#live-build, the scripts that make up live-build read their configuration with the #{source}# command from a single directory named #{config/}#. As constructing this directory by hand would be time-consuming and error-prone, the #{lb config}# command can be used to create the initial skeleton configuration tree. +[311][para] +Issuing #{lb config}# without any arguments creates the #{config/}# subdirectory which is populated with some default settings in configuration files, and two skeleton trees named #{auto/}# and #{local/}#. +[312][code] + + $$ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + + +[313][para] +Using #{lb config}# without any arguments would be suitable for users who need a very basic image, or who intend to provide a more complete configuration via #{auto/config}# later (see {Managing a configuration}#managing-a-configuration for details). +[314][para] +Normally, you will want to specify some options. For example, to specify which package manager to use while building the image: +[315][code] + + $$ lb config --apt aptitude + + +[316][para] +It is possible to specify many options, such as: +[317][code] + + $$ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + + +[318][para] +A full list of options is available in the #{lb_config}# man page. +[319][heading] +The #{lb build}# command +[320][para] +The #{lb build}# command reads in your configuration from the #{config/}# directory. It then runs the lower level commands needed to build your Live system. +[321][heading] +The #{lb clean}# command +[322][para] +It is the job of the #{lb clean}# command to remove various parts of a build so subsequent builds can start from a clean state. By default, #{chroot}#, #{binary}# and #{source}# stages are cleaned, but the cache is left intact. Also, individual stages can be cleaned. For example, if you have made changes that only affect the binary stage, use #{lb clean --binary}# prior to building a new binary. If your changes invalidate the bootstrap and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or #{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man page for a full list of options. +[323][heading] +The live-boot package +[324][para] +live-boot is a collection of scripts providing hooks for the /{initramfs-tools}/, used to generate an initramfs capable of booting live systems, such as those created by live-build. This includes the live system ISOs, netboot tarballs, and USB stick images. +[325][para] +At boot time it will look for read-only media containing a #{/live/}# directory where a root filesystem (often a compressed filesystem image like squashfs) is stored. If found, it will create a writable environment, using aufs, for Debian like systems to boot from. +[326][para] +More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter on initramfs. +[327][heading] +The live-config package +[328][para] +live-config consists of the scripts that run at boot time after live-boot to configure the live system automatically. It handles such tasks as setting the hostname, locales and timezone, creating the live user, inhibiting cron jobs and performing autologin of the live user. +[329][heading] +Managing a configuration +[330][heading] +Managing a configuration +[331][para] +This chapter explains how to manage a live configuration from initial creation, through successive revisions and successive releases of both the live-build software and the live image itself. +[332][heading] +Dealing with configuration changes +[333][para] +Live configurations rarely are perfect on the first try. It may be fine to pass #{lb config}# options from the command-line to perform a single build, but it is more typical to revise those options and build again until you are satisfied. To support these changes, you will need auto scripts which ensure your configuration is kept in a consistent state. +[334][heading] +Why use auto scripts? What do they do? +[335][para] +The #{lb config}# command stores the options you pass to it in #{config/*}# files along with many other options set to default values. If you run #{lb config}# again, it will not reset any option that was defaulted based on your initial options. So, for example, if you run #{lb config}# again with a new value for #{--binary-images}#, any dependent options that were defaulted for the old image type may no longer work with the new ones. Nor are these files intended to be read or edited. They store values for over a hundred options, so nobody, let alone yourself, will be able to see in these which options you actually specified. And finally, if you run #{lb config}#, then upgrade live-build and it happens to rename an option, #{config/*}# would still contain variables named after the old option that are no longer valid. +[336][para] +For all these reasons, #{auto/*}# scripts will make your life easier. They are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# commands that are designed to help you manage your configuration. The #{auto/config}# script stores your #{lb config}# command with all desired options, the #{auto/clean}# script removes the files containing configuration variable values, and the #{auto/build}# script keeps a #{build.log}# of each build. Each of these scripts is run automatically every time you run the corresponding #{lb}# command. By using these scripts, your configuration is easier to read and is kept internally consistent from one revision to the next. Also, it will be much easier for you identify and fix options which need to change when you upgrade live-build after reading the updated documentation. +[337][heading] +Use example auto scripts +[338][para] +For your convenience, live-build comes with example auto shell scripts to copy and edit. Start a new, default configuration, then copy the examples into it: +[339][code] + + $$ mkdir mylive && cd mylive && lb config + $$ mkdir auto + $$ cp /usr/share/doc/live-build/examples/auto/* auto/ + + +[340][para] +Edit #{auto/config}#, adding any options as you see fit. For instance: +[341][code] + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "$${@}" + + +[342][para] +Now, each time you use #{lb config}#, #{auto/config}# will reset the configuration based on these options. When you want to make changes to them, edit the options in this file instead of passing them to #{lb config}#. When you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files along with any other build products. And finally, when you use #{lb build}#, a log of the build will be written by #{auto/build}# in #{build.log}#. +[343][para] +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. +[344][heading] +Clone a configuration published via Git +[345][para] +Use the #{lb config --config}# option to clone a Git repository that contains a live system configuration. If you would like to base your configuration on one maintained by the $${project}, look at http://live-systems.org/gitweb/ for the repository named #{live-images}# in the category #{Packages}#. This repository contains the configurations for the live systems {prebuilt images}#downloading-prebuilt-images. +[346][para] +For example, to build a standard image, use the #{live-images}# repository as follows: +[347][code] + + $$ mkdir live-images && cd live-images + $$ lb config --config git://live-systems.org/git/live-images.git + $$ cd images/standard + + +[348][para] +Edit #{auto/config}# and any other things you need in the #{config}# tree to suit your needs. For example, the unofficial non-free prebuilt images are made by simply adding #{--archive-areas "main contrib non-free"}#. +[349][para] +You may optionally define a shortcut in your Git configuration by adding the following to your #{$${HOME}/.gitconfig}#: +[350][code] + + [url "git://live-systems.org/git/"] + insteadOf = lso: + + +[351][para] +This enables you to use #{lso:}# anywhere you need to specify the address of a #{live-systems.org}# git repository. If you also drop the optional #{.git}# suffix, starting a new image using this configuration is as easy as: +[352][code] + + $$ lb config --config lso:live-images + + +[353][para] +Cloning the entire #{live-images}# repository pulls the configurations used for several images. If you feel like building a different image after you have finished with the first one, change to another directory and again and optionally, make any changes to suit your needs. +[354][para] +In any case, remember that every time you will have to build the image as superuser: #{lb build}# +[355][heading] +Customizing contents +[356][heading] +Customization overview +[357][para] +This chapter gives an overview of the various ways in which you may customize a live system. +[358][heading] +Build time vs. boot time configuration +[359][para] +Live system configuration options are divided into build-time options which are options that are applied at build time and boot-time options which are applied at boot time. Boot-time options are further divided into those occurring early in the boot, applied by the live-boot package, and those that happen later in the boot, applied by live-config. Any boot-time option may be modified by the user by specifying it at the boot prompt. The image may also be built with default boot parameters so users can normally just boot directly to the live system without specifying any options when all of the defaults are suitable. In particular, the argument to #{lb --bootappend-live}# consists of any default kernel command line options for the Live system, such as persistence, keyboard layouts, or timezone. See {Customizing locale and language}#customizing-locale-and-language, for example. +[360][para] +Build-time configuration options are described in the #{lb config}# man page. Boot-time options are described in the man pages for live-boot and live-config. Although the live-boot and live-config packages are installed within the live system you are building, it is recommended that you also install them on your build system for easy reference when you are working on your configuration. It is safe to do so, as none of the scripts contained within them are executed unless the system is configured as a live system. +[361][heading] +Stages of the build +[362][para] +The build process is divided into stages, with various customizations applied in sequence in each. The first stage to run is the *{bootstrap}* stage. This is the initial phase of populating the chroot directory with packages to make a barebones Debian system. This is followed by the *{chroot}* stage, which completes the construction of chroot directory, populating it with all of the packages listed in the configuration, along with any other materials. Most customization of content occurs in this stage. The final stage of preparing the live image is the *{binary}* stage, which builds a bootable image, using the contents of the chroot directory to construct the root filesystem for the Live system, and including the installer and any other additional material on the target medium outside of the Live system's filesystem. After the live image is built, if enabled, the source tarball is built in the *{source}* stage. +[363][para] +Within each of these stages, there is a particular sequence in which commands are applied. These are arranged in such a way as to ensure customizations can be layered in a reasonable fashion. For example, within the *{chroot}* stage, preseeds are applied before any packages are installed, packages are installed before any locally included files are copied, and hooks are run later, after all of the materials are in place. +[364][heading] +Supplement lb config with files +[365][para] +Although #{lb config}# creates a skeletal configuration in the #{config/}# directory, to accomplish your goals, you may need to provide additional files in subdirectories of #{config/}#. Depending on where the files are stored in the configuration, they may be copied into the live system's filesystem or into the binary image filesystem, or may provide build-time configurations of the system that would be cumbersome to pass as command-line options. You may include things such as custom lists of packages, custom artwork, or hook scripts to run either at build time or at boot time, boosting the already considerable flexibility of debian-live with code of your own. +[366][heading] +Customization tasks +[367][para] +The following chapters are organized by the kinds of customization task users typically perform: {Customizing package installation}#customizing-package-installation, {Customizing contents}#customizing-contents and {Customizing locale and language}#customizing-locale-and-language cover just a few of the things you might want to do. +[368][heading] +Customizing package installation +[369][heading] +Customizing package installation +[370][para] +Perhaps the most basic customization of a live system is the selection of packages to be included in the image. This chapter guides you through the various build-time options to customize live-build's installation of packages. The broadest choices influencing which packages are available to install in the image are the distribution and archive areas. To ensure decent download speeds, you should choose a nearby distribution mirror. You can also add your own repositories for backports, experimental or custom packages, or include packages directly as files. You can define lists of packages, including metapackages which will install many related packages at once, such as packages for a particular desktop or language. Finally, a number of options give some control over /{apt}/, or if you prefer, /{aptitude}/, at build time when packages are installed. You may find these handy if you use a proxy, want to disable installation of recommended packages to save space, or need to control which versions of packages are installed via APT pinning, to name a few possibilities. +[371][heading] +Package sources +[372][heading] +Distribution, archive areas and mode +[373][para] +The distribution you choose has the broadest impact on which packages are available to include in your live image. Specify the codename, which defaults to $${testing} for the $${testing} version of live-build. Any current distribution carried in the archive may be specified by its codename here. (See {Terms}#terms for more details.) The #{--distribution}# option not only influences the source of packages within the archive, but also instructs live-build to behave as needed to build each supported distribution. For example, to build against the *{unstable}* release, sid, specify: +[374][code] + + $$ lb config --distribution sid + + +[375][para] +Within the distribution archive, archive areas are major divisions of the archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only #{main}# contains software that is part of the Debian distribution, hence that is the default. One or more values may be specified, e.g. +[376][code] + + $$ lb config --archive-areas "main contrib non-free" + + +[377][para] +Experimental support is available for some Debian derivatives through a #{--mode}# option. By default, this option is set to #{debian}# only if you are building on a Debian or on an unknown system. If #{lb config}# is invoked on any of the supported derivatives, it will default to create an image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, the distribution names and archive areas for the specified derivative are supported instead of the ones for Debian. The mode also modifies live-build behaviour to suit the derivatives. +[378][para] +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The $${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. +[379][heading] +Distribution mirrors +[380][para] +The Debian archive is replicated across a large network of mirrors around the world so that people in each region can choose a nearby mirror for best download speed. Each of the #{--mirror-*}# options governs which distribution mirror is used at various stages of the build. Recall from {Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is when the chroot is initially populated by /{debootstrap}/ with a minimal system, and the *{chroot}* stage is when the chroot used to construct the live system's filesystem is built. Thus, the corresponding mirror switches are used for those stages, and later, in the *{binary}* stage, the #{--mirror-binary}# and #{--mirror-binary-security}# values are used, superseding any mirrors used in an earlier stage. +[381][heading] +Distribution mirrors used at build time +[382][para] +To set the distribution mirrors used at build time to point at a local mirror, it is sufficient to set #{--mirror-bootstrap}# and #{--mirror-chroot-security}# as follows. +[383][code] + + $$ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + + +[384][para] +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the #{--mirror-bootstrap}# value. +[385][heading] +Distribution mirrors used at run time +[386][para] +The #{--mirror-binary*}# options govern the distribution mirrors placed in the binary image. These may be used to install additional packages while running the live system. The defaults employ #{httpredir.debian.org}#, a service that chooses a geographically close mirror based, among other things, on the user's IP family and the availability of the mirrors. This is a suitable choice when you cannot predict which mirror will be best for all of your users. Or you may specify your own values as shown in the example below. An image built from this configuration would only be suitable for users on a network where "#{mirror}#" is reachable. +[387][code] + + $$ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + + +[388][heading] +Additional repositories +[389][para] +You may add more repositories, broadening your package choices beyond what is available in your target distribution. These may be, for example, for backports, experimental or custom packages. To configure additional repositories, create #{config/archives/your-repository.list.chroot}#, and/or #{config/archives/your-repository.list.binary}# files. As with the #{--mirror-*}# options, these govern the repositories used in the *{chroot}* stage when building the image, and in the *{binary}* stage, i.e. for use when running the live system. +[390][para] +For example, #{config/archives/live.list.chroot}# allows you to install packages from the debian-live snapshot repository at live system build time. +[391][code] + + deb http://live-systems.org/ sid-snapshots main contrib non-free + + +[392][para] +If you add the same line to #{config/archives/live.list.binary}#, the repository will be added to your live system's #{/etc/apt/sources.list.d/}# directory. +[393][para] +If such files exist, they will be picked up automatically. +[394][para] +You should also put the GPG key used to sign the repository into #{config/archives/your-repository.key.{binary,chroot}}# files. +[395][para] +Should you need custom APT pinning, such APT preferences snippets can be placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and will be automatically added to your live system's #{/etc/apt/preferences.d/}# directory. +[396][heading] +Choosing packages to install +[397][para] +There are a number of ways to choose which packages live-build will install in your image, covering a variety of different needs. You can simply name individual packages to install in a package list. You can also use metapackages in those lists, or select them using package control file fields. And finally, you may place package files in your #{config/}# tree, which is well suited to testing of new or experimental packages before they are available from a repository. +[398][heading] +Package lists +[399][para] +Package lists are a powerful way of expressing which packages should be installed. The list syntax supports conditional sections which makes it easy to build lists and adapt them for use in multiple configurations. Package names may also be injected into the list using shell helpers at build time. +[400][para] +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. +[401][heading] +Using metapackages +[402][para] +The simplest way to populate your package list is to use a task metapackage maintained by your distribution. For example: +[403][code] + + $$ lb config + $$ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + + +[404][para] +This supercedes the older predefined list method supported in #{live-build}# 2.x. Unlike predefined lists, task metapackages are not specific to the Live System project. Instead, they are maintained by specialist working groups within the distribution and therefore reflect the consensus of each group about which packages best serve the needs of the intended users. They also cover a much broader range of use cases than the predefined lists they replace. +[405][para] +All task metapackages are prefixed #{task-}#, so a quick way to determine which are available (though it may contain a handful of false hits that match the name but aren't metapackages) is to match on the package name with: +[406][code] + + $$ apt-cache search --names-only ^task- + + +[407][para] +In addition to these, you will find other metapackages with various purposes. Some are subsets of broader task packages, like #{gnome-core}#, while others are individual specialized parts of a Debian Pure Blend, such as the #{education-*}# metapackages. To list all metapackages in the archive, install the #{debtags}# package and list all packages with the #{role::metapackage}# tag as follows: +[408][code] + + $$ debtags search role::metapackage + + +[409][heading] +Local package lists +[410][para] +Whether you list metapackages, individual packages, or a combination of both, all local package lists are stored in #{config/package-lists/}#. Since more than one list can be used, this lends itself well to modular designs. For example, you may decide to devote one list to a particular choice of desktop, another to a collection of related packages that might as easily be used on top of a different desktop. This allows you to experiment with different combinations of sets of packages with a minimum of fuss, sharing common lists between different live image projects. +[411][para] +Package lists that exist in this directory need to have a #{.list}# suffix in order to be processed, and then an additional stage suffix, #{.chroot}# or #{.binary}# to indicate which stage the list is for. +[412][para] +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. +[413][heading] +Local binary package lists +[414][para] +To make a binary stage list, place a file suffixed with #{.list.binary}# in #{config/package-lists/}#. These packages are not installed in the live filesystem, but are included on the live medium under #{pool/}#. You would typically use such a list with one of the non-live installer variants. As mentioned above, if you want this list to be the same as your chroot stage list, simply use the #{.list}# suffix by itself. +[415][heading] +Generated package lists +[416][para] +It sometimes happens that the best way to compose a list is to generate it with a script. Any line starting with an exclamation point indicates a command to be executed within the chroot when the image is built. For example, one might include the line #{! grep-aptavail -n -sPackage -FPriority standard | sort}# in a package list to produce a sorted list of available packages with #{Priority: standard}#. +[417][para] +In fact, selecting packages with the #{grep-aptavail}# command (from the #{dctrl-tools}# package) is so useful that #{live-build}# provides a #{Packages}# helper script as a convenience. This script takes two arguments: #{field}# and #{pattern}#. Thus, you can create a list with the following contents: +[418][code] + + $$ lb config + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + + +[419][heading] +Using conditionals inside package lists +[420][para] +Any of the live-build configuration variables stored in #{config/*}# (minus the #{LB_}# prefix) may be used in conditional statements in package lists. Generally, this means any #{lb config}# option uppercased and with dashes changed to underscores. But in practice, it is only the ones that influence package selection that make sense, such as #{DISTRIBUTION}#, #{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. +[421][para] +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is specified: +[422][code] + + #if ARCHITECTURES amd64 + ia32-libs + #endif + + +[423][para] +You may test for any one of a number of values, e.g. to install /{memtest86+}/ if either #{--architectures i386}# or #{--architectures amd64}# is specified: +[424][code] + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + + +[425][para] +You may also test against variables that may contain more than one value, e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified via #{--archive-areas}#: +[426][code] + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + + +[427][para] +The nesting of conditionals is not supported. +[428][heading] +Removing packages at install time +[429][para] +You can list packages in files with #{.list.chroot_live}# and #{.list.chroot_install}# suffixes inside the #{config/package-lists}# directory. If both a live and an install list exist, the packages in the #{.list.chroot_live}# list are removed with a hook after the installation (if the user uses the installer). The packages in the #{.list.chroot_install}# list are present both in the live system and in the installed system. This is a special tweak for the installer and may be useful if you have #{--debian-installer live}# set in your config, and wish to remove live system-specific packages at install time. +[430][heading] +Desktop and language tasks +[431][para] +Desktop and language tasks are special cases that need some extra planning and configuration. Live images are different from Debian Installer images in this respect. In the Debian Installer, if the medium was prepared for a particular desktop environment flavour, the corresponding task will be automatically installed. Thus, there are internal #{gnome-desktop}#, #{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for tasks for languages, but the user's language choice during the install influences the selection of corresponding language tasks. +[432][para] +When developing a desktop live image, the image typically boots directly to a working desktop, the choices of both desktop and default language having been made at build time, not at run time as in the case of the Debian Installer. That's not to say that a live image couldn't be built to support multiple desktops or multiple languages and offer the user a choice, but that is not live-build's default behaviour. +[433][para] +Because there is no provision made automatically for language tasks, which include such things as language-specific fonts and input-method packages, if you want them, you need to specify them in your configuration. For example, a GNOME desktop image containing support for German might include these task metapackages: +[434][code] + + $$ lb config + $$ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $$ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + + +[435][heading] +Kernel flavour and version +[436][para] +One or more kernel flavours will be included in your image by default, depending on the architecture. You can choose different flavours via the #{--linux-flavours}# option. Each flavour is suffixed to the default stub #{linux-image}# to form each metapackage name which in turn depends on an exact kernel package to be included in your image. +[437][para] +Thus by default, an #{amd64}# architecture image will include the #{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture image will include the #{linux-image-586}# metapackage. +[438][para] +When more than one kernel package version is available in your configured archives, you can specify a different kernel package name stub with the #{--linux-packages}# option. For example, supposing you are building an #{amd64}# architecture image and add the experimental archive for testing purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# kernel. You would configure that image as follows: +[439][code] + + $$ lb config --linux-packages linux-image-3.18.0-trunk + $$ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + + +[440][heading] +Custom kernels +[441][para] +You can build and include your own custom kernels, so long as they are integrated within the Debian package management system. The live-build system does not support kernels not built as #{.deb}# packages. +[442][para] +The proper and recommended way to deploy your own kernel packages is to follow the instructions in the #{kernel-handbook}#. Remember to modify the ABI and flavour suffixes appropriately, then include a complete build of the #{linux}# and matching #{linux-latest}# packages in your repository. +[443][para] +If you opt to build the kernel packages without the matching metapackages, you need to specify an appropriate #{--linux-packages}# stub as discussed in {Kernel flavour and version}#kernel-flavour-and-version. As we explain in {Installing modified or third-party packages}#installing-modified-or-third-party-packages, it is best if you include your custom kernel packages in your own repository, though the alternatives discussed in that section work as well. +[444][para] +It is beyond the scope of this document to give advice on how to customize your kernel. However, you must at least ensure your configuration satisfies these minimum requirements: +[445][para] +_* Use an initial ramdisk. +[446][para] +_* Include the union filesystem module (i.e. usually #{aufs}#). +[447][para] +_* Include any other filesystem modules required by your configuration (i.e. usually #{squashfs}#). +[448][heading] +Installing modified or third-party packages +[449][para] +While it is against the philosophy of a live system, it may sometimes be necessary to build a live system with modified versions of packages that are in the Debian repository. This may be to modify or support additional features, languages and branding, or even to remove elements of existing packages that are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietary functionality. +[450][para] +This section does not cover advice regarding building or maintaining modified packages. Joachim Breitner's 'How to fork privately' method from http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html may be of interest, however. The creation of bespoke packages is covered in the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ and elsewhere. +[451][para] +There are two ways of installing modified custom packages: +[452][para] +_* #{packages.chroot}# +[453][para] +_* Using a custom APT repository +[454][para] +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" customizations but has a number of drawbacks, while using a custom APT repository is more time-consuming to set up. +[455][heading] +Using #{packages.chroot}# to install custom packages +[456][para] +To install a custom package, simply copy it to the #{config/packages.chroot/}# directory. Packages that are inside this directory will be automatically installed into the live system during build - you do not need to specify them elsewhere. +[457][para] +Packages *{must}* be named in the prescribed way. One simple way to do this is to use #{dpkg-name}#. +[458][para] +Using #{packages.chroot}# for installation of custom packages has disadvantages: +[459][para] +_* It is not possible to use secure APT. +[460][para] +_* You must install all appropriate packages in the #{config/packages.chroot/}# directory. +[461][para] +_* It does not lend itself to storing live system configurations in revision control. +[462][heading] +Using an APT repository to install custom packages +[463][para] +Unlike using #{packages.chroot}#, when using a custom APT repository you must ensure that you specify the packages elsewhere. See {Choosing packages to install}#choosing-packages-to-install for details. +[464][para] +While it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified packages. +[465][heading] +Custom packages and APT +[466][para] +live-build uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package available in two different repositories with different version numbers, APT will elect to install the package with the higher version number. +[467][para] +Because of this, you may wish to increment the version number in your custom packages' #{debian/changelog}# files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see {APT pinning}#apt-pinning for more information. +[468][heading] +Configuring APT at build time +[469][para] +You can configure APT through a number of options applied only at build time. (APT configuration used in the running live system may be configured in the normal way for live system contents, that is, by including the appropriate configurations through #{config/includes.chroot/}#.) For a complete list, look for options starting with #{apt}# in the #{lb_config}# man page. +[470][heading] +Choosing apt or aptitude +[471][para] +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages at build time. Which utility is used is governed by the #{--apt}# argument to #{lb config}#. Choose the method implementing the preferred behaviour for package installation, the notable difference being how missing packages are handled. +[472][para] +_* #{apt}#: With this method, if a missing package is specified, the package installation will fail. This is the default setting. +[473][para] +_* #{aptitude}#: With this method, if a missing package is specified, the package installation will succeed. +[474][heading] +Using a proxy with APT +[475][para] +One commonly required APT configuration is to deal with building an image behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# or #{--apt-http-proxy}# options as needed, e.g. +[476][code] + + $$ lb config --apt-http-proxy http://proxy/ + + +[477][heading] +Tweaking APT to save space +[478][para] +You may find yourself needing to save some space on the image medium, in which case one or the other or both of the following options may be of interest. +[479][para] +If you don't want to include APT indices in the image, you can omit those with: +[480][code] + + $$ lb config --apt-indices false + + +[481][para] +This will not influence the entries in #{/etc/apt/sources.list}#, but merely whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is that APT needs those indices in order to operate in the live system, so before performing #{apt-cache search}# or #{apt-get install}#, for instance, the user must #{apt-get update}# first to create those indices. +[482][para] +If you find the installation of recommended packages bloats your image too much, provided you are prepared to deal with the consequences discussed below, you may disable that default option of APT with: +[483][code] + + $$ lb config --apt-recommends false + + +[484][para] +The most important consequence of turning off recommends is that #{live-boot}# and #{live-config}# themselves recommend some packages that provide important functionality used by most Live configurations, such as #{user-setup}# which #{live-config}# recommends and is used to create the live user. In all but the most exceptional circumstances you need to add back at least some of these recommends to your package lists or else your image will not work as expected, if at all. Look at the recommended packages for each of the #{live-*}# packages included in your build and if you are not certain you can omit them, add them back into your package lists. +[485][para] +The more general consequence is that if you don't install recommended packages for any given package, that is, "packages that would be found together with this one in all but unusual installations" (Debian Policy Manual, section 7.2), some packages that users of your Live system actually need may be omitted. Therefore, we suggest you review the difference turning off recommends makes to your packages list (see the #{binary.packages}# file generated by #{lb build}#) and re-include in your list any missing packages that you still want installed. Alternatively, if you find you only want a small number of recommended packages left out, leave recommends enabled and set a negative APT pin priority on selected packages to prevent them from being installed, as explained in {APT pinning}#apt-pinning. +[486][heading] +Passing options to apt or aptitude +[487][para] +If there is not a #{lb config}# option to alter APT's behaviour in the way you need, use #{--apt-options}# or #{--aptitude-options}# to pass any options through to your configured APT tool. See the man pages for #{apt}# and #{aptitude}# for details. Note that both options have default values that you will need to retain in addition to any overrides you may provide. So, for example, suppose you have included something from #{snapshot.debian.org}# for testing purposes and want to specify #{Acquire::Check-Valid-Until=false}# to make APT happy with the stale #{Release}# file, you would do so as per the following example, appending the new option after the default value #{--yes}#: +[488][code] + + $$ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + + +[489][para] +Please check the man pages to fully understand these options and when to use them. This is an example only and should not be construed as advice to configure your image this way. This option would not be appropriate for, say, a final release of a live image. +[490][para] +For more complicated APT configurations involving #{apt.conf}# options you might want to create a #{config/apt/apt.conf}# file instead. See also the other #{apt-*}# options for a few convenient shortcuts for frequently needed options. +[491][heading] +APT pinning +[492][para] +For background, please first read the #{apt_preferences(5)}# man page. APT pinning can be configured either for build time, or else for run time. For the former, create #{config/archives/*.pref}#, #{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the latter, create #{config/includes.chroot/etc/apt/preferences}#. +[493][para] +Let's say you are building a $${testing} live system but need all the live packages that end up in the binary image to be installed from sid at build time. You need to add sid to your APT sources and pin the live packages from it higher, but all other packages from it lower, than the default priority. Thus, only the packages you want are installed from sid at build time and all others are taken from the target system distribution, $${testing}. The following will accomplish this: +[494][code] + + $$ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $$ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + + +[495][para] +Negative pin priorities will prevent a package from being installed, as in the case where you do not want a package that is recommended by another package. Suppose you are building an LXDE image using #{task-lxde-desktop}# in #{config/package-lists/desktop.list.chroot}#, but don't want the user prompted to store wifi passwords in the keyring. This metapackage depends on /{lxde-core}/, which recommends /{gksu}/, which in turn recommends /{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ package. This can be done by adding the following stanza to #{config/apt/preferences}#: +[496][code] + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + + +[497][heading] +Customizing contents +[498][heading] +Customizing contents +[499][para] +This chapter discusses fine-tuning customization of the live system contents beyond merely choosing which packages to include. Includes allow you to add or replace arbitrary files in your live system image, hooks allow you to execute arbitrary commands at different stages of the build and at boot time, and preseeding allows you to configure packages when they are installed by supplying answers to debconf questions. +[500][heading] +Includes +[501][para] +While ideally a live system would include files entirely provided by unmodified packages, it is sometimes convenient to provide or modify some content by means of files. Using includes, it is possible to add (or replace) arbitrary files in your live system image. live-build provides two mechanisms for using them: +[502][para] +_* Chroot local includes: These allow you to add or replace files to the chroot/Live filesystem. Please see {Live/chroot local includes}#live-chroot-local-includes for more information. +[503][para] +_* Binary local includes: These allow you to add or replace files in the binary image. Please see {Binary local includes}#binary-local-includes for more information. +[504][para] +Please see {Terms}#terms for more information about the distinction between the "Live" and "binary" images. +[505][heading] +Live/chroot local includes +[506][para] +Chroot local includes can be used to add or replace files in the chroot/Live filesystem so that they may be used in the Live system. A typical use is to populate the skeleton user directory (#{/etc/skel}#) used by the Live system to create the live user's home directory. Another is to supply configuration files that can be simply added or replaced in the image without processing; see {Live/chroot local hooks}#live-chroot-local-hooks if processing is needed. +[507][para] +To include files, simply add them to your #{config/includes.chroot}# directory. This directory corresponds to the root directory #{/}# of the live system. For example, to add a file #{/var/www/index.html}# in the live system, use: +[508][code] + + $$ mkdir -p config/includes.chroot/var/www + $$ cp /path/to/my/index.html config/includes.chroot/var/www + + +[509][para] +Your configuration will then have the following layout: +[510][code] + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + + +[511][para] +Chroot local includes are installed after package installation so that files installed by packages are overwritten. +[512][heading] +Binary local includes +[513][para] +To include material such as documentation or videos on the medium filesystem so that it is accessible immediately upon insertion of the medium without booting the Live system, you can use binary local includes. This works in a similar fashion to chroot local includes. For example, suppose the files #{~/video_demo.*}# are demo videos of the live system described by and linked to by an HTML index page. Simply copy the material to #{config/includes.binary/}# as follows: +[514][code] + + $$ cp ~/video_demo.* config/includes.binary/ + + +[515][para] +These files will now appear in the root directory of the live medium. +[516][heading] +Hooks +[517][para] +Hooks allow commands to be performed in the chroot and binary stages of the build in order to customize the image. +[518][heading] +Live/chroot local hooks +[519][para] +To run commands in the chroot stage, create a hook script with a #{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run in the chroot after the rest of your chroot configuration has been applied, so remember to ensure your configuration includes all packages and files your hook needs in order to run. See the example chroot hook scripts for various common chroot customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. +[520][heading] +Boot-time hooks +[521][para] +To execute commands at boot time, you can supply live-config hooks as explained in the "Customization" section of its man page. Examine live-config's own hooks provided in #{/lib/live/config/}#, noting the sequence numbers. Then provide your own hook prefixed with an appropriate sequence number, either as a chroot local include in #{config/includes.chroot/lib/live/config/}#, or as a custom package as discussed in {Installing modified or third-party packages}#installing-modified-or-third-party-packages. +[522][heading] +Binary local hooks +[523][para] +To run commands in the binary stage, create a hook script with a #{.hook.binary}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run after all other binary commands are run, but before binary_checksums, the very last binary command. The commands in your hook do not run in the chroot, so take care to not modify any files outside of the build tree, or you may damage your build system! See the example binary hook scripts for various common binary customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. +[524][heading] +Preseeding Debconf questions +[525][para] +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf preseed files and are installed by live-build using #{debconf-set-selections}# during the corresponding stage. +[526][para] +For more information about debconf, please see #{debconf(7)}# in the /{debconf}/ package. +[527][heading] +Customizing run time behaviours +[528][heading] +Customizing run time behaviours +[529][para] +All configuration that is done during run time is done by live-config. Here are some of the most common options of live-config that users are interested in. A full list of all possibilities can be found in the man page of live-config. +[530][heading] +Customizing the live user +[531][para] +One important consideration is that the live user is created by live-boot at boot time, not by live-build at build time. This not only influences where materials relating to the live user are introduced in your build, as discussed in {Live/chroot local includes}#live-chroot-local-includes, but also any groups and permissions associated with the live user. +[532][para] +You can specify additional groups that the live user will belong to by using any of the possibilities to configure live-config. For example, to add the live user to the #{fuse}# group, you can either add the following file in #{config/includes.chroot/etc/live/config/user-setup.conf}#: +[533][code] + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + + +[534][para] +or use #{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# as a boot parameter. +[535][para] +It is also possible to change the default username "user" and the default password "live". If you want to do that for any reason, you can easily achieve it as follows: +[536][para] +To change the default username you can simply specify it in your config: +[537][code] + + $$ lb config --bootappend-live "boot=live components username=live-user" + + +[538][para] +One possible way of changing the default password is by means of a hook as described in {Boot-time hooks}#boot-time-hooks. In order to do that you can use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, prefix it accordingly (e.g. 2000-passwd) and add it to #{config/includes.chroot/lib/live/config/}# +[539][heading] +Customizing locale and language +[540][para] +When the live system boots, language is involved in two steps: +[541][para] +_* the locale generation +[542][para] +_* setting the keyboard configuration +[543][para] +The default locale when building a Live system is #{locales=en_US.UTF-8}#. To define the locale that should be generated, use the #{locales}# parameter in the #{--bootappend-live}# option of #{lb config}#, e.g. +[544][code] + + $$ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + + +[545][para] +Multiple locales may be specified as a comma-delimited list. +[546][para] +This parameter, as well as the keyboard configuration parameters indicated below, can also be used at the kernel command line. You can specify a locale by #{language_country}# (in which case the default encoding is used) or the full #{language_country.encoding}# word. A list of supported locales and the encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. +[547][para] +Both the console and X keyboard configuration are performed by #{live-config}# using the #{console-setup}# package. To configure them, use the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and #{keyboard-model}# boot parameters via the #{--bootappend-live}# option. Valid options for these can be found in #{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a given language, try searching for the English name of the language and/or the country where the language is spoken, e.g: +[548][code] + +$$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + + +[549][para] +Note that each variant lists the layout to which it applies in the description. +[550][para] +Often, only the layout needs to be configured. For example, to get the locale files for German and Swiss German keyboard layout in X use: +[551][code] + + $$ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + + +[552][para] +However, for very specific use cases, you may wish to include other parameters. For example, to set up a French system with a French-Dvorak layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: +[553][code] + + $$ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + + +[554][para] +Multiple values may be specified as comma-delimited lists for each of the #{keyboard-*}# options, with the exception of #{keyboard-model}#, which accepts only one value. Please see the #{keyboard(5)}# man page for details and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and #{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are given, they will be matched one-to-one with #{keyboard-layouts}# values (see #{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to define two layouts, the default being US QWERTY and the other being US Dvorak, use: +[555][code] + + $$ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + + +[556][heading] +Persistence +[557][para] +A live cd paradigm is a pre-installed system which runs from read-only media, like a cdrom, where writes and modifications do not survive reboots of the host hardware which runs it. +[558][para] +A live system is a generalization of this paradigm and thus supports other media in addition to CDs; but still, in its default behaviour, it should be considered read-only and all the run-time evolutions of the system are lost at shutdown. +[559][para] +'Persistence' is a common name for different kinds of solutions for saving across reboots some, or all, of this run-time evolution of the system. To understand how it works it would be handy to know that even if the system is booted and run from read-only media, modifications to the files and directories are written on writable media, typically a ram disk (tmpfs) and ram disks' data do not survive reboots. +[560][para] +The data stored on this ramdisk should be saved on a writable persistent medium like local storage media, a network share or even a session of a multisession (re)writable CD/DVD. All these media are supported in live systems in different ways, and all but the last one require a special boot parameter to be specified at boot time: #{persistence}#. +[561][para] +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not set), local storage media (e.g. hard disks, USB drives) will be probed for persistence volumes during boot. It is possible to restrict which types of persistence volumes to use by specifying certain boot parameters described in the live-boot(7) man page. A persistence volume is any of the following: +[562][para] +_* a partition, identified by its GPT name. +[563][para] +_* a filesystem, identified by its filesystem label. +[564][para] +_* an image file located on the root of any readable filesystem (even an NTFS partition of a foreign OS), identified by its filename. +[565][para] +The volume label for overlays must be #{persistence}# but it will be ignored unless it contains in its root a file named #{persistence.conf}# which is used to fully customize the volume's persistence, this is to say, specifying the directories that you want to save in your persistence volume after a reboot. See {The persistence.conf file}#persistence-conf for more details. +[566][para] +Here are some examples of how to prepare a volume to be used for persistence. It can be, for instance, an ext4 partition on a hard disk or on a usb key created with, e.g.: +[567][code] + + # mkfs.ext4 -L persistence /dev/sdb1 + + +[568][para] +See also {Using the space left on a USB stick}#using-usb-extra-space. +[569][para] +If you already have a partition on your device, you could just change the label with one of the following: +[570][code] + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + + +[571][para] +Here's an example of how to create an ext4-based image file to be used for persistence: +[572][code] + + $$ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $$ /sbin/mkfs.ext4 -F persistence + + +[573][para] +Once the image file is created, as an example, to make #{/usr}# persistent but only saving the changes you make to that directory and not all the contents of #{/usr}#, you can use the "union" option. If the image file is located in your home directory, copy it to the root of your hard drive's filesystem and mount it in #{/mnt}# as follows: +[574][code] + + # cp persistence / + # mount -t ext4 /persistence /mnt + + +[575][para] +Then, create the #{persistence.conf}# file adding content and unmount the image file. +[576][code] + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + + +[577][para] +Now, reboot into your live medium with the boot parameter "persistence". +[578][heading] +The persistence.conf file +[579][para] +A volume with the label #{persistence}# must be configured by means of the #{persistence.conf}# file to make arbitrary directories persistent. That file, located on the volume's filesystem root, controls which directories it makes persistent, and in which way. +[580][para] +How custom overlay mounts are configured is described in full detail in the persistence.conf(5) man page, but a simple example should be sufficient for most uses. Let's say we want to make our home directory and APT cache persistent in an ext4 filesystem on the /dev/sdb1 partition: +[581][code] + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + + +[582][para] +Then we reboot. During the first boot the contents of #{/home}# and #{/var/cache/apt}# will be copied into the persistence volume, and from then on all changes to these directories will live in the persistence volume. Please note that any paths listed in the #{persistence.conf}# file cannot contain white spaces or the special #{.}# and #{..}# path components. Also, neither #{/lib}#, #{/lib/live}# (or any of their sub-directories) nor #{/}# can be made persistent using custom mounts. As a workaround for this limitation you can add #{/ union}# to your #{persistence.conf}# file to achieve full persistence. +[583][heading] +Using more than one persistence store +[584][para] +There are different methods of using multiple persistence store for different use cases. For instance, using several volumes at the same time or selecting only one, among various, for very specific purposes. +[585][para] +Several different custom overlay volumes (with their own #{persistence.conf}# files) can be used at the same time, but if several volumes make the same directory persistent, only one of them will be used. If any two mounts are "nested" (i.e. one is a sub-directory of the other) the parent will be mounted before the child so no mount will be hidden by the other. Nested custom mounts are problematic if they are listed in the same #{persistence.conf}# file. See the persistence.conf(5) man page for how to handle that case if you really need it (hint: you usually don't). +[586][para] +One possible use case: If you wish to store the user data i.e. #{/home}# and the superuser data i.e. #{/root}# in different partitions, create two partitions with the #{persistence}# label and add a #{persistence.conf}# file in each one like this, #{# echo "/home" > persistence.conf}# for the first partition that will save the user's files and #{# echo "/root" > persistence.conf}# for the second partition which will store the superuser's files. Finally, use the #{persistence}# boot parameter. +[587][para] +If a user would need multiple persistence store of the same type for different locations or testing, such as #{private}# and #{work}#, the boot parameter #{persistence-label}# used in conjunction with the boot parameter #{persistence}# will allow for multiple but unique persistence media. An example would be if a user wanted to use a persistence partition labeled #{private}# for personal data like browser bookmarks or other types, they would use the boot parameters: #{persistence}# #{persistence-label=private}#. And to store work related data, like documents, research projects or other types, they would use the boot parameters: #{persistence}# #{persistence-label=work}#. +[588][para] +It is important to remember that each of these volumes, #{private}# and #{work}#, also needs a #{persistence.conf}# file in its root. The live-boot man page contains more information about how to use these labels with legacy names. +[589][heading] +Using persistence with encryption +[590][para] +Using the persistence feature means that some sensible data might get exposed to risk. Especially if the persistent data is stored on a portable device such as a usb stick or an external hard drive. That is when encryption comes in handy. Even if the entire procedure might seem complicated because of the number of steps to be taken, it is really easy to handle encrypted partitions with live-boot. In order to use *{luks}*, which is the supported encryption type, you need to install /{cryptsetup}/ both on the machine you are creating the encrypted partition with and also in the live system you are going to use the encrypted persistent partition with. +[591][para] +To install /{cryptsetup}/ on your machine: +[592][code] + + # apt-get install cryptsetup + + +[593][para] +To install /{cryptsetup}/ in your live system, add it to your package-lists: +[594][code] + + $$ lb config + $$ echo "cryptsetup" > config/package-lists/encryption.list.chroot + + +[595][para] +Once you have your live system with /{cryptsetup}/, you basically only need to create a new partition, encrypt it and boot with the #{persistence}# and #{persistence-encryption=luks}# parameters. We could have already anticipated this step and added the boot parameters following the usual procedure: +[596][code] + + $$ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + + +[597][para] +Let's go into the details for all of those who are not familiar with encryption. In the following example we are going to use a partition on a usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need to determine which partition is the one you are going to use in your specific case. +[598][para] +The first step is plugging in your usb stick and determine which device it is. The recommended method of listing devices in live-manual is using #{ls -l /dev/disk/by-id}#. After that, create a new partition and then, encrypt it with a passphrase as follows: +[599][code] + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + + +[600][para] +Then open the luks partition in the virtual device mapper. Use any name you like. We use *{live}* here as an example: +[601][code] + + # cryptsetup luksOpen /dev/sdc2 live + + +[602][para] +The next step is filling the device with zeros before creating the filesystem: +[603][code] + + # dd if=/dev/zero of=/dev/mapper/live + + +[604][para] +Now, we are ready to create the filesystem. Notice that we are adding the label #{persistence}# so that the device is mounted as persistence store at boot time. +[605][code] + + # mkfs.ext4 -L persistence /dev/mapper/live + + +[606][para] +To continue with our setup, we need to mount the device, for example in #{/mnt}#. +[607][code] + + # mount /dev/mapper/live /mnt + + +[608][para] +And create the #{persistence.conf}# file in the root of the partition. This is, as explained before, strictly necessary. See {The persistence.conf file}#persistence-conf. +[609][code] + + # echo "/ union" > /mnt/persistence.conf + + +[610][para] +Then unmount the mount point: +[611][code] + + # umount /mnt + + +[612][para] +And optionally, although it might be a good way of securing the data we have just added to the partition, we can close the device: +[613][code] + + # cryptsetup luksClose live + + +[614][para] +Let's summarize the process. So far, we have created an encryption capable live system, which can be copied to a usb stick as explained in {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also created an encrypted partition, which can be located in the same usb stick to carry it around and we have configured the encrypted partition to be used as persistence store. So now, we only need to boot the live system. At boot time, live-boot will prompt us for the passphrase and will mount the encrypted partition to be used for persistence. +[615][heading] +Customizing the binary image +[616][heading] +Customizing the binary image +[617][heading] +Bootloaders +[618][para] +live-build uses /{syslinux}/ and some of its derivatives (depending on the image type) as bootloaders by default. They can be easily customized to suit your needs. +[619][para] +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# into #{config/bootloaders}# and edit the files in there. If you do not want to bother modifying all supported bootloader configurations, only providing a local customized copy of one of the bootloaders, e.g. *{isolinux}* in #{config/bootloaders/isolinux}# is enough too, depending on your use case. +[620][para] +When modifying one of the default themes, if you want to use a personalized background image that will be displayed together with the boot menu, add a splash.png picture of 640x480 pixels. Then, remove the splash.svg file. +[621][para] +There are many possibilities when it comes to making changes. For instance, syslinux derivatives are configured by default with a timeout of 0 (zero) which means that they will pause indefinitely at their splash screen until you press a key. +[622][para] +To modify the boot timeout of a default #{iso-hybrid}# image just edit a default *{isolinux.cfg}* file specifying the timeout in units of 1/10 seconds. A modified *{isolinux.cfg}* to boot after five seconds would be similar to this: +[623][code] + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + + +[624][heading] +ISO metadata +[625][para] +When creating an ISO9660 binary image, you can use the following options to add various textual metadata for your image. This can help you easily identify the version or configuration of an image without booting it. +[626][para] +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the application that will be on the image. The maximum length for this field is 128 characters. +[627][para] +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the preparer of the image, usually with some contact details. The default for this option is the live-build version you are using, which may help with debugging later. The maximum length for this field is 128 characters. +[628][para] +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters. +[629][para] +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of the image. This is used as a user-visible label on some platforms such as Windows and Apple Mac OS. The maximum length for this field is 32 characters. +[630][heading] +Customizing Debian Installer +[631][heading] +Customizing Debian Installer +[632][para] +Live system images can be integrated with Debian Installer. There are a number of different types of installation, varying in what is included and how the installer operates. +[633][para] +Please note the careful use of capital letters when referring to the "Debian Installer" in this section - when used like this we refer explicitly to the official installer for the Debian system, not anything else. It is often seen abbreviated to "d-i". +[634][heading] +Types of Debian Installer +[635][para] +The three main types of installer are: +[636][para] +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". +[637][para] +On such images, Debian is installed by fetching and installing .deb packages using /{debootstrap}/, from local media or some network-based network, resulting in a default Debian system being installed to the hard disk. +[638][para] +This whole process can be preseeded and customized in a number of ways; see the relevant pages in the Debian Installer manual for more information. Once you have a working preseeding file, live-build can automatically put it in the image and enable it for you. +[639][para] +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. +[640][para] +Installation will proceed in an identical fashion to the "normal" installation described above, but at the actual package installation stage, instead of using /{debootstrap}/ to fetch and install packages, the live filesystem image is copied to the target. This is achieved with a special udeb called live-installer. +[641][para] +After this stage, the Debian Installer continues as normal, installing and configuring items such as bootloaders and local users, etc. +[642][para] +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. +[643][para] +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. +[644][para] +Note that by default, live-build does not include Debian Installer images in the images, it needs to be specifically enabled with #{lb config}#. Also, please note that for the "Desktop" installer to work, the kernel of the live system must match the kernel #{d-i}# uses for the specified architecture. For example: +[645][code] + + $$ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $$ echo debian-installer-launcher >> config/package-lists/my.list.chroot + + +[646][heading] +Customizing Debian Installer by preseeding +[647][para] +As described in the Debian Installer Manual, Appendix B at https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a way to set answers to questions asked during the installation process, without having to manually enter the answers while the installation is running. This makes it possible to fully automate most types of installation and even offers some features not available during normal installations." This kind of customization is best accomplished with live-build by placing the configuration in a #{preseed.cfg}# file included in #{config/includes.installer/}#. For example, to preseed setting the locale to #{en_US}#: +[648][code] + + $$ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + + +[649][heading] +Customizing Debian Installer content +[650][para] +For experimental or debugging purposes, you might want to include locally built #{d-i}# component udeb packages. Place these in #{config/packages.binary/}# to include them in the image. Additional or replacement files and directories may be included in the installer initrd as well, in a similar fashion to {Live/chroot local includes}#live-chroot-local-includes, by placing the material in #{config/includes.installer/}#. +[651][heading] +Project +[652][heading] +Contributing to the project +[653][heading] +Contributing to the project +[654][para] +When submitting a contribution, please clearly identify its copyright holder and include any applicable licensing statement. Note that to be accepted, the contribution must be licensed under the same license as the rest of the documents, namely, GPL version 3 or later. +[655][para] +Contributions to the project, such as translations and patches, are greatly welcome. Anyone can directly commit to the repositories, however, we ask you to send bigger changes to the mailing list to discuss them first. See the section {Contact}#contact for more information. +[656][para] +The $${project} uses Git as version control system and source code management. As explained in {Git repositories}#git-repositories there are two main development branches: *{debian}* and *{debian-next}*. Everybody can commit to the debian-next branches of the live-boot, live-build, live-config, live-images, live-manual and live-tools repositories. +[657][para] +However, there are certain restrictions. The server will reject: +[658][para] +_* Non fast-forward pushes. +[659][para] +_* Merge commits. +[660][para] +_* Adding or removing tags or branches. +[661][para] +Even though all commits might be revised, we ask you to use your common sense and make good commits with good commit messages. +[662][para] +_* Write commit messages that consist of complete, meaningful sentences in English, starting with a capital letter and ending with a full stop. Usually, these will start with the form "Fixing/Adding/Removing/Correcting/Translating/...". +[663][para] +_* Write good commit messages. The first line must be an accurate summary of the contents of the commit which will be included in the changelog. If you need to make some further explanations, write them below leaving a blank line after the first one and then another blank line after each paragraph. Lines of paragraphs should not exceed 80 characters in length. +[664][para] +_* Commit atomically, this is to say, do not mix unrelated things in the same commit. Make one different commit for each change you make. +[665][heading] +Making changes +[666][para] +In order to push to the repositories, you must follow the following procedure. Here we use live-manual as an example so replace it with the name of the repository you want to work with. For detailed information on how to edit live-manual see {Contributing to this document}#how-to-contribute. +[667][para] +_* Fetch the public commit key: +[668][code] + + $$ mkdir -p ~/.ssh/keys + $$ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $$ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $$ chmod 0600 ~/.ssh/keys/git@live-systems.org* + + +[669][para] +_* Add the following section to your openssh-client config: +[670][code] + + $$ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + + +[671][para] +_* Check out a clone of live-manual through ssh: +[672][code] + + $$ git clone git@live-systems.org:/live-manual.git + $$ cd live-manual && git checkout debian-next + + +[673][para] +_* Make sure you have Git author and email set: +[674][code] + + $$ git config user.name "John Doe" + $$ git config user.email john@example.org + + +[675][para] +*{Important:}* Remember that you should commit any changes on the *{debian-next}* branch. +[676][para] +_* Make your changes. In this example you would first write a new section dealing with applying patches and then prepare to commit adding the files and writing your commit message like this: +[677][code] + + $$ git commit -a -m "Adding a section on applying patches." + + +[678][para] +_* Push the commit to the server: +[679][code] + + $$ git push + + +[680][heading] +Reporting bugs +[681][heading] +Reporting bugs +[682][para] +Live systems are far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug. It is better to fill a report twice than never. However, this chapter includes recommendations on how to file good bug reports. +[683][para] +For the impatient: +[684][para] +_* Always check first the image status updates on our homepage at http://live-systems.org/ for known issues. +[685][para] +_* Before submitting a bug report always try to reproduce the bug with the *{most recent versions}* of the branch of live-build, live-boot, live-config and live-tools that you're using (like the newest 4.x version of live-build if you're using live-build 4). +[686][para] +_* Try to give *{as specific information as possible}* about the bug. This includes (at least) the version of live-build, live-boot, live-config, and live-tools used and the distribution of the live system you are building. +[687][heading] +Known issues +[688][para] +Since Debian *{testing}* and Debian *{unstable}* distributions are moving targets, when you specify either of them as the target system distribution, a successful build may not always be possible. +[689][para] +If this causes too much difficulty for you, do not build a system based on *{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always defaults to the *{stable}* release. +[690][para] +Currently known issues are listed under the section 'status' on our homepage at http://live-systems.org/. +[691][para] +It is out of the scope of this manual to train you to correctly identify and fix problems in packages of the development distributions, however, there are two things you can always try: If a build fails when the target distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work either, revert to *{testing}* and pin the newer version of the failing package from *{unstable}* (see {APT pinning}#apt-pinning for details). +[692][heading] +Rebuild from scratch +[693][para] +To ensure that a particular bug is not caused by an uncleanly built system, please always rebuild the whole live system from scratch to see if the bug is reproducible. +[694][heading] +Use up-to-date packages +[695][para] +Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. Make sure your build system is up-to-date and any packages included in your image are up-to-date as well. +[696][heading] +Collect information +[697][para] +Please provide enough information with your report. Include, at least, the exact version of live-build where the bug is encountered and the steps to reproduce it. Please use your common sense and provide any other relevant information if you think that it might help in solving the problem. +[698][para] +To make the most out of your bug report, we require at least the following information: +[699][para] +_* Architecture of the host system +[700][para] +_* Distribution of the host system +[701][para] +_* Version of live-build on the host system +[702][para] +_* Version of /{debootstrap}/ on the host system +[703][para] +_* Architecture of the live system +[704][para] +_* Distribution of the live system +[705][para] +_* Version of live-boot on the live system +[706][para] +_* Version of live-config on the live system +[707][para] +_* Version of live-tools on the live system +[708][para] +You can generate a log of the build process by using the #{tee}# command. We recommend doing this automatically with an #{auto/build}# script (see {Managing a configuration}#managing-a-configuration for details). +[709][code] + + # lb build 2>&1 | tee build.log + + +[710][para] +At boot time, live-boot and live-config store their logfiles in #{/var/log/live/}#. Check them for error messages. +[711][para] +Additionally, to rule out other errors, it is always a good idea to tar up your #{config/}# directory and upload it somewhere (do *{not}* send it as an attachment to the mailing list), so that we can try to reproduce the errors you encountered. If this is difficult (e.g. due to size) you can use the output of #{lb config --dump}# which produces a summary of your config tree (i.e. lists files in subdirectories of #{config/}# but does not include them). +[712][para] +Remember to send in any logs that were produced with English locale settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or #{LC_ALL=en_US}#. +[713][heading] +Isolate the failing case if possible +[714][para] +If possible, isolate the failing case to the smallest possible change that breaks. It is not always easy to do this so if you cannot manage it for your report, do not worry. However, if you plan your development cycle well, using small enough change sets per iteration, you may be able to isolate the problem by constructing a simpler 'base' configuration that closely matches your actual configuration plus just the broken change set added to it. If you have a hard time sorting out which of your changes broke, it may be that you are including too much in each change set and should develop in smaller increments. +[715][heading] +Use the correct package to report the bug against +[716][para] +If you do not know what component is responsible for the bug or if the bug is a general bug concerning live systems, you can fill a bug against the debian-live pseudo-package. +[717][para] +However, we would appreciate it if you try to narrow it down according to where the bug appears. +[718][heading] +At build time while bootstrapping +[719][para] +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to the bootstrapping tool itself. +[720][para] +In both cases, this is not a bug in the live system, but rather in Debian itself and probably we cannot fix it directly. Please report such a bug against the bootstrapping tool or the failing package. +[721][heading] +At build time while installing packages +[722][para] +live-build installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system. +[723][para] +If this is the case, this is not a bug in the live system, but rather in Debian - please report it against the failing package. Running /{debootstrap}/ separately from the Live system build or running #{lb bootstrap --debug}# will give you more information. +[724][para] +Also, if you are using a local mirror and/or any sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror. +[725][heading] +At boot time +[726][para] +If your image does not boot, please report it to the mailing list together with the information requested in {Collect information}#collect-information. Do not forget to mention, how/when the image failed exactly, whether using virtualization or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful. +[727][heading] +At run time +[728][para] +If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in the live system. However: +[729][heading] +Do the research +[730][para] +Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem. There is always a chance that it has been discussed elsewhere and a possible solution, patch, or workaround has been proposed. +[731][para] +You should pay particular attention to the live systems mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report. +[732][para] +In addition, you should check the current bug lists for live-build, live-boot, live-config and live-tools to see whether something similar has already been reported. +[733][heading] +Where to report bugs +[734][para] +The $${project} keeps track of all bugs in the Bug Tracking System (BTS). For information on how to use the system, please see https://bugs.debian.org/. You can also submit the bugs by using the #{reportbug}# command from the package with the same name. +[735][para] +In general, you should report build time errors against the live-build package, boot time errors against live-boot, and run time errors against live-config. If you are unsure of which package is appropriate or need more help before submitting a bug report, please report it against the debian-live pseudo-package. We will then take care about it and reassign it where appropriate. +[736][para] +Please note that bugs found in distributions derived from Debian (such as Ubuntu and others) should *{not}* be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages. +[737][heading] +Coding Style +[738][heading] +Coding Style +[739][para] +This chapter documents the coding style used in live systems. +[740][heading] +Compatibility +[741][para] +_* Don't use syntax or semantics that are unique to the Bash shell. For example, the use of array constructs. +[742][para] +_* Only use the POSIX subset - for example, use $$(foo) over `foo`. +[743][para] +_* You can check your scripts with 'sh -n' and 'checkbashisms'. +[744][para] +_* Make sure all shell code runs with 'set -e'. +[745][heading] +Indenting +[746][para] +_* Always use tabs over spaces. +[747][heading] +Wrapping +[748][para] +_* Generally, lines are 80 chars at maximum. +[749][para] +_* Use the "Linux style" of line breaks: +[750][para] +Bad: +[751][code] + + if foo; then + bar + fi + + +[752][para] +Good: +[753][code] + + if foo + then + bar + fi + + +[754][para] +_* The same holds for functions: +[755][para] +Bad: +[756][code] + + Foo () { + bar + } + + +[757][para] +Good: +[758][code] + + Foo () + { + bar + } + + +[759][heading] +Variables +[760][para] +_* Variables are always in capital letters. +[761][para] +_* Variables used in live-build always start with #{LB_}# prefix. +[762][para] +_* Internal temporary variables in live-build should start with the #{\_LB_}# prefix. +[763][para] +_* Local variables start with live-build #{\_\_LB_}# prefix. +[764][para] +_* Variables in connection to a boot parameter in live-config start with #{LIVE_}#. +[765][para] +_* All other variables in live-config start with #{_}# prefix. +[766][para] +_* Use braces around variables; e.g. write #{$${FOO}}# instead of #{$$FOO}#. +[767][para] +_* Always protect variables with quotes to respect potential whitespaces: write #{"$${FOO}"}# not #{$${FOO}}#. +[768][para] +_* For consistency reasons, always use quotes when assigning values to variables: +[769][para] +Bad: +[770][code] + + FOO=bar + + +[771][para] +Good: +[772][code] + + FOO="bar" + + +[773][para] +_* If multiple variables are used, quote the full expression: +[774][para] +Bad: +[775][code] + + if [ -f "$${FOO}"/foo/"$${BAR}"/bar ] + then + foobar + fi + + +[776][para] +Good: +[777][code] + + if [ -f "$${FOO}/foo/$${BAR}/bar" ] + then + foobar + fi + + +[778][heading] +Miscellaneous +[779][para] +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, e.g. "#{sed -e 's|foo|bar|'}#" (without ""). +[780][para] +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" "#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test -x /bin/foo; ...}#". +[781][para] +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and faster in execution. +[782][para] +_* Use capitalized names for functions to limit messing with the users environment. +[783][heading] +Procedures +[784][heading] +Procedures +[785][para] +This chapter documents the procedures within the $${project} for various tasks that need cooperation with other teams in Debian. +[786][heading] +Major Releases +[787][para] +Releasing a new stable major version of Debian includes a lot of different teams working together to make it happen. At some point, the Live team comes in and builds live system images. The requirements to do this are: +[788][para] +_* A mirror containing the released versions for the debian and debian-security archives which the debian-live buildd can access. +[789][para] +_* The names of the image need to be known (e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). +[790][para] +_* The data from debian-cd needs to be synced (udeb exclude lists). +[791][para] +_* Images are built and mirrored on cdimage.debian.org. +[792][heading] +Point Releases +[793][para] +_* Again, we need updated mirrors of debian and debian-security. +[794][para] +_* Images are built and mirrored on cdimage.debian.org. +[795][para] +_* Send announcement mail. +[796][heading] +Last Point Release of a Debian Release +[797][para] +Remember to adjust both chroot and binary mirrors when building the last set ofimages for a Debian release after it has been moved away from ftp.debian.org toarchive.debian.org. That way, old prebuilt live images are still useful withoutuser modifications. +[798][heading] +Point release announcement template +[799][para] +An announcement mail for point releases can be generated using the template below and the following command: +[800][code] + + $$ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + + +[801][para] +Please check the mail carefully before sending and pass it to others for proof-reading. +[802][code] + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + + +[803][heading] +Git repositories +[804][heading] +Git repositories +[805][para] +The list of all the available repositories of the $${project} can be found at http://live-systems.org/gitweb/. The project's git URLs have the form: #{protocol://live-systems.org/git/repository}#. Thus, in order to clone live-manual read-only, launch: +[806][code] + + $$ git clone git://live-systems.org/git/live-manual.git + + +[807][para] +Or, +[808][code] + + $$ git clone https://live-systems.org/git/live-manual.git + + +[809][para] +Or, +[810][code] + + $$ git clone http://live-systems.org/git/live-manual.git + + +[811][para] +The cloning addresses with write permission have the form: #{git@live-systems.org:/repository}#. +[812][para] +So, again, to clone live-manual over ssh you must type: +[813][code] + + $$ git clone git@live-systems.org:live-manual.git + + +[814][para] +The git tree is made up of several different branches. The *{debian}* and the *{debian-next}* branches are particularly noteworthy because they contain the actual work that will eventually be included in each new release. +[815][para] +After cloning any of the existing repositories, you will be on the *{debian}* branch. This is appropriate to take a look at the state of the project's latest release but before starting work it is crucial to switch to the *{debian-next}* branch. To do so: +[816][code] + + $$ git checkout debian-next + + +[817][para] +The *{debian-next}* branch, which is not always fast-forward, is where all the changes are committed first before being merged into the *{debian}* branch. To make an analogy, it is like a testing ground. If you are working on this branch and need to pull, you will have to do a #{git pull --rebase}# so that your local modifications are staged while pulling from the server and then your changes will be put on top of it all. +[818][heading] +Handling multiple repositories +[819][para] +If you intend to clone several of the live systems repositories and want to switch to the *{debian-next}* branch right away to check the latest code, write a patch or contribute with a translation you ought to know that the git server provides a #{mrconfig}# file to ease the handling of multiple repositories. In order to use it you need to install the /{mr}/ package and after that, launch: +[820][code] + + $$ mr bootstrap http://live-systems.org/other/mr/mrconfig + + +[821][para] +This command will automatically clone and checkout to the *{debian-next}* branch the development repositories of the Debian packages produced by the project. These include, among others, the live-images repository, which contains the configurations used for the prebuilt images that the project publishes for general use. For more information on how to use this repository, see {Clone a configuration published via Git}#clone-configuration-via-git +[822][heading] +Examples +[823][heading] +Examples +[824][heading] +Examples +[825][para] +This chapter covers example builds for specific use cases with live systems. If you are new to building your own live system images, we recommend you first look at the three tutorials in sequence, as each one teaches new techniques that will help you use and understand the remaining examples. +[826][heading] +Using the examples +[827][para] +To use these examples you need a system to build them on that meets the requirements listed in {Requirements}#requirements and has live-build installed as described in {Installing live-build}#installing-live-build. +[828][para] +Note that, for the sake of brevity, in these examples we do not specify a local mirror to use for the build. You can speed up downloads considerably if you use a local mirror. You may specify the options when you use #{lb config}#, as described in {Distribution mirrors used at build time}#distribution-mirrors-build-time, or for more convenience, set the default for your build system in #{/etc/live/build.conf}#. Simply create this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your preferred mirror. All other mirrors used in the build will be defaulted from these values. For example: +[829][code] + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + + +[830][heading] +Tutorial 1: A default image +[831][para] +*{Use case:}* Create a simple first image, learning the basics of live-build. +[832][para] +In this tutorial, we will build a default ISO hybrid live system image containing only base packages (no Xorg) and some live system support packages, as a first exercise in using live-build. +[833][para] +You can't get much simpler than this: +[834][code] + + $$ mkdir tutorial1 ; cd tutorial1 ; lb config + + +[835][para] +Examine the contents of the #{config/}# directory if you wish. You will see stored here a skeletal configuration, ready to customize or, in this case, use immediately to build a default image. +[836][para] +Now, as superuser, build the image, saving a log as you build with #{tee}#. +[837][code] + + # lb build 2>&1 | tee build.log + + +[838][para] +Assuming all goes well, after a while, the current directory will contain #{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly in a virtual machine as described in {Testing an ISO image with Qemu}#testing-iso-with-qemu and {Testing an ISO image with VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media or a USB flash device as described in {Burning an ISO image to a physical medium}#burning-iso-image and {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb, respectively. +[839][heading] +Tutorial 2: A web browser utility +[840][para] +*{Use case:}* Create a web browser utility image, learning how to apply customizations. +[841][para] +In this tutorial, we will create an image suitable for use as a web browser utility, serving as an introduction to customizing live system images. +[842][code] + + $$ mkdir tutorial2 + $$ cd tutorial2 + $$ lb config + $$ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + + +[843][para] +Our choice of LXDE for this example reflects our desire to provide a minimal desktop environment, since the focus of the image is the single use we have in mind, the web browser. We could go even further and provide a default configuration for the web browser in #{config/includes.chroot/etc/iceweasel/profile/}#, or additional support packages for viewing various kinds of web content, but we leave this as an exercise for the reader. +[844][para] +Build the image, again as superuser, keeping a log as in {Tutorial 1}#tutorial-1: +[845][code] + + # lb build 2>&1 | tee build.log + + +[846][para] +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. +[847][heading] +Tutorial 3: A personalized image +[848][para] +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. +[849][para] +Since we will be changing our personalized image over a number of revisions, and we want to track those changes, trying things experimentally and possibly reverting them if things don't work out, we will keep our configuration in the popular #{git}# version control system. We will also use the best practice of autoconfiguration via #{auto}# scripts as described in {Managing a configuration}#managing-a-configuration. +[850][heading] +First revision +[851][code] + + $$ mkdir -p tutorial3/auto + $$ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $$ cd tutorial3 + + +[852][para] +Edit #{auto/config}# to read as follows: +[853][code] + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "$${@}" + + +[854][para] +Perform #{lb config}# to generate the config tree, using the #{auto/config}# script you just created: +[855][code] + + $$ lb config + + +[856][para] +Now populate your local package list: +[857][code] + + $$ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + + +[858][para] +First, #{--architectures i386}# ensures that on our #{amd64}# build system, we build a 32-bit version suitable for use on most machines. Second, we use #{--linux-flavours 686-pae}# because we don't anticipate using this image on much older systems. Third, we have chosen the /{lxde}/ task metapackage to give us a minimal desktop. And finally, we have added two initial favourite packages: /{iceweasel}/ and /{xchat}/. +[859][para] +Now, build the image: +[860][code] + + # lb build + + +[861][para] +Note that unlike in the first two tutorials, we no longer have to type #{2>&1 | tee build.log}# as that is now included in #{auto/build}#. +[862][para] +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are satisfied it works, it's time to initialize our #{git}# repository, adding only the auto scripts we just created, and then make the first commit: +[863][code] + + $$ git init + $$ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $$ git add . + $$ git commit -m "Initial import." + + +[864][heading] +Second revision +[865][para] +In this revision, we're going to clean up from the first build, add the /{vlc}/ package to our configuration, rebuild, test and commit. +[866][para] +The #{lb clean}# command will clean up all generated files from the previous build except for the cache, which saves having to re-download packages. This ensures that the subsequent #{lb build}# will re-run all stages to regenerate the files from our new configuration. +[867][code] + + # lb clean + + +[868][para] +Now append the /{vlc}/ package to our local package list in #{config/package-lists/my.list.chroot}#: +[869][code] + + $$ echo vlc >> config/package-lists/my.list.chroot + + +[870][para] +Build again: +[871][code] + +# lb build + + +[872][para] +Test, and when you're satisfied, commit the next revision: +[873][code] + + $$ git commit -a -m "Adding vlc media player." + + +[874][para] +Of course, more complicated changes to the configuration are possible, perhaps adding files in subdirectories of #{config/}#. When you commit new revisions, just take care not to hand edit or commit the top-level files in #{config}# containing #{LB_*}# variables, as these are build products, too, and are always cleaned up by #{lb clean}# and re-created with #{lb config}# via their respective #{auto}# scripts. +[875][para] +We've come to the end of our tutorial series. While many more kinds of customization are possible, even just using the few features explored in these simple examples, an almost infinite variety of different images can be created. The remaining examples in this section cover several other use cases drawn from the collected experiences of users of live systems. +[876][heading] +A VNC Kiosk Client +[877][para] +*{Use case:}* Create an image with live-build to boot directly to a VNC server. +[878][para] +Make a build directory and create an skeletal configuration inside it, disabling recommends to make a minimal system. And then create two initial package lists: the first one generated with a script provided by live-build named #{Packages}# (see {Generated package lists}#generated-package-lists), and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and /{xvnc4viewer}/. +[879][code] + + $$ mkdir vnc-kiosk-client + $$ cd vnc-kiosk-client + $$ lb config -a i386 -k 686-pae --apt-recommends false + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $$ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + + +[880][para] +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you may need to re-add some recommended packages to make your image work properly. +[881][para] +An easy way to list recommends is using /{apt-cache}/. For example: +[882][code] + + $$ apt-cache depends live-config live-boot + + +[883][para] +In this example we found out that we had to re-include several packages recommended by live-config and live-boot: #{user-setup}# to make autologin work and #{sudo}# as an essential program to shutdown the system. Besides, it could be handy to add #{live-tools}# to be able to copy the image to RAM and #{eject}# to eventually eject the live medium. So: +[884][code] + + $$ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + + +[885][para] +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# and put a custom #{.xsession}# in it for the default user that will launch /{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a server at #{192.168.1.2}#: +[886][code] + + $$ mkdir -p config/includes.chroot/etc/skel + $$ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + + +[887][para] +Build the image: +[888][code] + + # lb build + + +[889][para] +Enjoy. +[890][heading] +A base image for a 128MB USB key +[891][para] +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. +[892][para] +When optimizing an image to fit a certain media size, you need to understand the tradeoffs you are making between size and functionality. In this example, we trim only so much as to make room for additional material within a 128MB media size, but without doing anything to destroy the integrity of the packages contained within, such as the purging of locale data via the /{localepurge}/ package, or other such "intrusive" optimizations. Of particular note, we use #{--debootstrap-options}# to create a minimal system from scratch. +[893][code] + + $$ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + + +[894][para] +To make the image work properly, we must re-add, at least, two recommended packages which are left out by the #{--apt-recommends false}# option. See {Tweaking APT to save space}#tweaking-apt-to-save-space +[895][code] + + $$ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + + +[896][para] +Now, build the image in the usual way: +[897][code] + + # lb build 2>&1 | tee build.log + + +[898][para] +On the author's system at the time of writing this, the above configuration produced a 110MB image. This compares favourably with the 192MB image produced by the default configuration in {Tutorial 1}#tutorial-1. +[899][para] +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount of space, the tradeoff being that you need to do an #{apt-get update}# before using /{apt}/ in the live system. Dropping recommended packages with #{--apt-recommends false}# saves some additional space, at the expense of omitting some packages you might otherwise expect to be there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal system from the start. Not automatically including firmware packages with #{--firmware-chroot false}# saves some space too. And finally, #{--memtest none}# prevents the installation of a memory tester. +[900][para] +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. +[901][heading] +A localized GNOME desktop and installer +[902][para] +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. +[903][para] +We want to make an iso-hybrid image for i386 architecture using our preferred desktop, in this case GNOME, containing all of the same packages that would be installed by the standard Debian installer for GNOME. +[904][para] +Our initial problem is the discovery of the names of the appropriate language tasks. Currently, live-build cannot help with this. While we might get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, which can be used to dig it out of the task descriptions in tasksel-data, so to prepare, make sure you have both of those things: +[905][code] + + # apt-get install dctrl-tools tasksel-data + + +[906][para] +Now we can search for the appropriate tasks, first with: +[907][code] + + $$ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + + +[908][para] +By this command, we discover the task is called, plainly enough, german. Now to find the related tasks: +[909][code] + + $$ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + + +[910][para] +At boot time we will generate the *{de_CH.UTF-8}* locale and select the *{ch}* keyboard layout. Now let's put the pieces together. Recalling from {Using metapackages}#using-metapackages that task metapackages are prefixed #{task-}#, we just specify these language boot parameters, then add standard priority packages and all our discovered task metapackages to our package list as follows: +[911][code] + + $$ mkdir live-gnome-ch + $$ cd live-gnome-ch + $$ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $$ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $$ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + + +[912][para] +Note that we have included the /{debian-installer-launcher}/ package to launch the installer from the live desktop. The #{586}# kernel flavour, which is currently necessary for the launcher to work properly, will be included by default. +[913][heading] +Appendix +[914][heading] +Style guide +[915][heading] +Style guide +[916][heading] +Guidelines for authors +[917][para] +This section deals with some general considerations to be taken into account when writing technical documentation for live-manual. They are divided into linguistic features and recommended procedures. +[918][para] +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute +[919][heading] +Linguistic features +[920][para] +_* /{Use plain English}/ +[921][para] +Keep in mind that a high percentage of your readers are not native speakers of English. So as a general rule try to use short, meaningful sentences, followed by a full stop. +[922][para] +This does not mean that you have to use a simplistic, naive style. It is a suggestion to try to avoid, as much as possible, complex subordinate sentences that make the text difficult to understand for non-native speakers of English. +[923][para] +_* /{Variety of English}/ +[924][para] +The most widely spread varieties of English are British and American so it is very likely that most authors will use either one or the other. In a collaborative environment, the ideal variety would be "International English" but it is very difficult, not to say impossible, to decide on which variety among all the existing ones, is the best to use. +[925][para] +We expect that different varieties may mix without creating misunderstandings but in general terms you should try to be coherent and before deciding on using British, American or any other English flavour at your discretion, please take a look at how other people write and try to imitate them. +[926][para] +_* /{Be balanced}/ +[927][para] +Do not be biased. Avoid including references to ideologies completely unrelated to live-manual. Technical writing should be as neutral as possible. It is in the very nature of scientific writing. +[928][para] +_* /{Be politically correct}/ +[929][para] +Try to avoid sexist language as much as possible. If you need to make references to the third person singular preferably use "they" rather than "he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. +[930][para] +_* /{Be concise}/ +[931][para] +Go straight to the point and do not wander around aimlessly. Give as much information as necessary but do not give more information than necessary, this is to say, do not explain unnecessary details. Your readers are intelligent. Presume some previous knowledge on their part. +[932][para] +_* /{Minimize translation work}/ +[933][para] +Keep in mind that whatever you write will have to be translated into several other languages. This implies that a number of people will have to do an extra work if you add useless or redundant information. +[934][para] +_* /{Be coherent}/ +[935][para] +As suggested before, it is almost impossible to standardize a collaborative document into a perfectly unified whole. However, every effort on your side to write in a coherent way with the rest of the authors will be appreciated. +[936][para] +_* /{Be cohesive}/ +[937][para] +Use as many text-forming devices as necessary to make your text cohesive and unambiguous. (Text-forming devices are linguistic markers such as connectors). +[938][para] +_* /{Be descriptive}/ +[939][para] +It is preferable to describe the point in one or several paragraphs than merely using a number of sentences in a typical "changelog" style. Describe it! Your readers will appreciate it. +[940][para] +_* /{Dictionary}/ +[941][para] +Look up the meaning of words in a dictionary or encyclopedia if you do not know how to express certain concepts in English. But keep in mind that a dictionary can either be your best friend or can turn into your worst enemy if you do not know how to use it correctly. +[942][para] +English has the largest vocabulary that exists (with over one million words). Many of these words are borrowings from other languages. When looking up the meaning of words in a bilingual dictionary the tendency of a non-native speaker of English is to choose the one that sounds more similar in their mother tongue. This often turns into an excessively formal discourse which does not sound quite natural in English. +[943][para] +As a general rule, if a concept can be expressed using different synonyms, it is a good advice to choose the first word proposed by the dictionary. If in doubt, choosing words of Germanic origin (Usually monosyllabic words) is often the right thing to do. Be warned that these two techniques might produce a rather informal discourse but at least your choice of words will be of wide use and generally accepted. +[944][para] +Using a dictionary of collocations is recommended. They are extremely helpful when it comes to know which words usually occur together. +[945][para] +Again it is a good practice to learn from the work of others. Using a search engine to check how other authors use certain expressions may help a lot. +[946][para] +_* /{False friends, idioms and other idiomatic expressions}/ +[947][para] +Watch out for false friends. No matter how proficient you are in a foreign language you cannot help falling from time to time in the trap of the so called "false friends", words that look similar in two languages but whose meanings or uses might be completely different. +[948][para] +Try to avoid idioms as much as possible. "Idioms" are expressions that may convey a completely different meaning from what their individual words seem to mean. Sometimes, idioms might be difficult to understand even for native speakers of English! +[949][para] +_* /{Avoid slang, abbreviations, contractions...}/ +[950][para] +Even though you are encouraged to use plain, everyday English, technical writing belongs to the formal register of the language. +[951][para] +Try to avoid slang, unusual abbreviations that are difficult to understand and above all contractions that try to imitate the spoken language. Not to mention typical irc and family friendly expressions. +[952][heading] +Procedures +[953][para] +_* /{Test before write}/ +[954][para] +It is important that authors test their examples before adding them to live-manual to ensure that everything works as described. Testing on a clean chroot or VM can be a good starting point. Besides, it would be ideal if the tests were then carried out on different machines with different hardware to spot possible problems that may arise. +[955][para] +_* /{Examples}/ +[956][para] +When providing an example try to be as specific as you can. An example is, after all, just an example. +[957][para] +It is often better to use a line that only applies to a specific case than using abstractions that may confuse your readers. In this case you can provide a brief explanation of the effects of the proposed example. +[958][para] +There may be some exceptions when the example suggests using some potentially dangerous commands that, if misused, may cause data loss or other similar undesirable effects. In this case you should provide a thorough explanation of the possible side effects. +[959][para] +_* /{External links}/ +[960][para] +Links to external sites should only be used when the information on those sites is crucial when it comes to understanding a special point. Even so, try to use links to external sites as sparsely as possible. Internet links are likely to change from time to time resulting in broken links and leaving your arguments in an incomplete state. +[961][para] +Besides, people who read the manual offline will not have the chance to follow those links. +[962][para] +_* /{Avoid branding and things that violate the license under which the manual is published}/ +[963][para] +Try to avoid branding as much as possible. Keep in mind that other downstream projects might make use of the documentation you write. So you are complicating things for them if you add certain specific material. +[964][para] +live-manual is licensed under the GNU GPL. This has a number of implications that apply to the distribution of the material (of any kind, including copyrighted graphics or logos) that is published with it. +[965][para] +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ +[966][para] +- Brainstorm!. You need to organize your ideas first in a logical sequence of events. +[967][para] +- Once you have somehow organized those ideas in your mind write a first draft. +[968][para] +- Revise grammar, syntax and spelling. Keep in mind that the proper names of the releases, such as $${testing} or sid, should not be capitalized when referred to as code names. In order to check the spelling you can run the "spell" target. i.e. #{make spell}# +[969][para] +- Improve your statements and redo any part if necessary. +[970][para] +_* /{Chapters}/ +[971][para] +Use the conventional numbering system for chapters and subtitles. e.g. 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup below. +[972][para] +If you have to enumerate a series of steps or stages in your description, you can also use ordinal numbers: First, second, third ... or First, Then, After that, Finally ... Alternatively you can use bulleted items. +[973][para] +_* /{Markup}/ +[974][para] +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to process the text files and produce a multiple format output. It is recommended to take a look at {SiSU's manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get familiar with its markup, or else type: +[975][code] + + $$ sisu --help markup + + +[976][para] +Here are some markup examples that may prove useful: +[977][para] +- For emphasis/bold text: +[978][code] + +*{foo}* or !{foo}! + + +[979][para] +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. +[980][para] +- For italics: +[981][code] + +/{foo}/ + + +[982][para] +produces: /{foo}/. Use them e.g. for the names of Debian packages. +[983][para] +- For monospace: +[984][code] + +#{foo}# + + +[985][para] +produces: #{foo}#. Use it e.g. for the names of commands. And also to highlight some key words or things like paths. +[986][para] +- For code blocks: +[987][code] + + code{ + + $$ foo + # bar + + }code + + +[988][para] +produces: +[989][code] + + $$ foo + # bar + + +[990][para] +Use #{code{}# to open and #{}code}# to close the tags. It is important to remember to leave a space at the beginning of each line of code. +[991][heading] +Guidelines for translators +[992][para] +This section deals with some general considerations to be taken into account when translating the contents of live-manual. +[993][para] +As a general recommendation, translators should have read and understood the translation rules that apply to their specific languages. Usually, translation groups and mailing lists provide information on how to produce translated work that complies with Debian quality standards. +[994][para] +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation +[995][heading] +Translation hints +[996][para] +_* /{Comments}/ +[997][para] +The role of the translator is to convey as faithfully as possible the meaning of words, sentences, paragraphs and texts as written by the original authors into their target language. +[998][para] +So they should refrain from adding personal comments or extra bits of information of their own. If they want to add a comment for other translators working on the same documents, they can leave it in the space reserved for that. That is, the header of the strings in the *{po}* files preceded by a number sign *{#}*. Most graphical translation programs can automatically handle those types of comments. +[999][para] +_* /{TN, Translator's Note}/ +[1000][para] +It is perfectly acceptable however, to include a word or an expression in brackets in the translated text if, and only if, that makes the meaning of a difficult word or expression clearer to the reader. Inside the brackets the translator should make evident that the addition was theirs using the abbreviation "TN" or "Translator's Note". +[1001][para] +_* /{Impersonal sentences}/ +[1002][para] +Documents written in English make an extensive use of the impersonal form "you". In some other languages that do not share this characteristic, this might give the false impression that the original texts are directly addressing the reader when they are actually not doing so. Translators must be aware of that fact and reflect it in their language as accurately as possible. +[1003][para] +_* /{False friends}/ +[1004][para] +The trap of "false friends" explained before especially applies to translators. Double check the meaning of suspicious false friends if in doubt. +[1005][para] +_* /{Markup}/ +[1006][para] +Translators working initially with *{pot}* files and later on with *{po}* files will find many markup features in the strings. They can translate the text anyway, as long as it is translatable, but it is extremely important that they use exactly the same markup as the original English version. +[1007][para] +_* /{Code blocks}/ +[1008][para] +Even though the code blocks are usually untranslatable, including them in the translation is the only way to score a 100% complete translation. And even though it means more work at first because it might require the intervention of the translators if the code changes, it is the best way, in the long run, to identify what has already been translated and what has not when checking the integrity of the .po files. +[1009][para] +_* /{Newlines}/ +[1010][para] +The translated texts need to have the exact same newlines as the original texts. Be careful to press the "Enter" key or type *{\n}* if they appear in the original files. These newlines often appear, for instance, in the code blocks. +[1011][para] +Make no mistake, this does not mean that the translated text needs to have the same length as the English version. That is nearly impossible. +[1012][para] +_* /{Untranslatable strings}/ +[1013][para] +Translators should never translate: +[1014][para] +- The code names of releases (which should be written in lowercase) +[1015][para] +- The names of programs +[1016][para] +- The commands given as examples +[1017][para] +- Metadata (often between colons *{:metadata:}*) +[1018][para] +- Links +[1019][para] +- Paths +[1019][heading] +Endnotes +[1020][heading] +Endnotes +[1021][heading] +Book Index +[1022][heading] +Index +[92m-------------------------------[0m +en/live-manual.ssm +length contents array: 1026 +last ocn: 1022 +length bookindex: 0 +lib/sdp/ao_output_debugs.d:283 +en/live-manual.ssm +[91m~ document run failure ~[0m (LDC v2068) + en/live-manual.ssm +(LDC v2068) +[35m~ run failure ~[0m diff --git a/markup/pod-samples/pod/live-manual/media/text/lm_sdp2.txt b/markup/pod-samples/pod/live-manual/media/text/lm_sdp2.txt new file mode 100644 index 0000000..8ceb6e6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/lm_sdp2.txt @@ -0,0 +1,2743 @@ +------------------------------- +lib/sdp/ao_output_debugs.d:50 +[1][heading] +@title +[2][heading] +About +[3][heading] +About this manual +[4][heading] +About this manual +[5][para] +This manual serves as a single access point to all documentation related to the $${project} and in particular applies to the software produced by the project for the Debian 9.0 "$${stable}" release. An up-to-date version can always be found at http://live-systems.org/ +[6][para] +While live-manual is primarily focused on helping you build a live system and not on end-user topics, an end user may find some useful information in these sections: {The Basics}#the-basics covers downloading prebuilt images and preparing images to be booted from media or the network, either using the web builder or running live-build directly on your system. {Customizing run time behaviours}#customizing-run-time-behaviours describes some options that may be specified at the boot prompt, such as selecting a keyboard layout and locale, and using persistence. +[7][para] +Some of the commands mentioned in the text must be executed with superuser privileges which can be obtained by becoming the root user via #{su}# or by using #{sudo}#. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by #{$$}# or #{#}# respectively. This symbol is not a part of the command. +[8][heading] +For the impatient +[9][para] +While we believe that everything in this manual is important to at least some of our users, we realize it is a lot of material to cover and that you may wish to experience early success using the software before delving into the details. Therefore, we suggest reading in the following order. +[10][para] +First, read this chapter, {About this manual}#about-manual, from the beginning and ending with the {Terms}#terms section. Next, skip to the three tutorials at the front of the {Examples}#examples section designed to teach you image building and customization basics. Read {Using the examples}#using-the-examples first, followed by {Tutorial 1: A default image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these tutorials, you will have a taste of what can be done with live systems. +[11][para] +We encourage you to return to more in-depth study of the manual, perhaps next reading {The basics}#the-basics, skimming or skipping {Building a netboot image}#building-netboot-image, and finishing by reading the {Customization overview}#customization-overview and the chapters that follow it. By this point, we hope you are thoroughly excited by what can be done with live systems and motivated to read the rest of the manual, cover-to-cover. +[12][heading] +Terms +[13][para] +_* *{Live system}*: An operating system that can boot without installation to a hard drive. Live systems do not alter local operating system(s) or file(s) already installed on the computer hard drive unless instructed to do so. Live systems are typically booted from media such as CDs, DVDs or USB sticks. Some may also boot over the network (via netboot images, see {Building a netboot image}#building-netboot-image), and over the Internet (via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). +[14][para] +_* *{Live medium}*: As distinct from live system, the live medium refers to the CD, DVD or USB stick where the binary produced by live-build and used to boot the live system is written. More broadly, the term also refers to any place where this binary resides for the purposes of booting the live system, such as the location for the network boot files. +[15][para] +_* *{$${project}}*: The project which maintains, among others, the live-boot, live-build, live-config, live-tools and live-manual packages. +[16][para] +_* *{Host system}*: The environment used to create the live system. +[17][para] +_* *{Target system}*: The environment used to run the live system. +[18][para] +_* *{live-boot}*: A collection of scripts used to boot live systems. +[19][para] +_* *{live-build}*: A collection of scripts used to build customized live systems. +[20][para] +_* *{live-config}*: A collection of scripts used to configure a live system during the boot process. +[21][para] +_* *{live-tools}*: A collection of additional scripts used to perform useful tasks within a running live system. +[22][para] +_* *{live-manual}*: This document is maintained in a package called live-manual. +[23][para] +_* *{Debian Installer (d-i)}*: The official installation system for the Debian distribution. +[24][para] +_* *{Boot parameters}*: Parameters that can be entered at the bootloader prompt to influence the kernel or live-config. +[25][para] +_* *{chroot}*: The /{chroot}/ program, #{chroot(8)}#, enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting. +[26][para] +_* *{Binary image}*: A file containing the live system, such as live-image-i386.hybrid.iso or live-image-i386.img. +[27][para] +_* *{Target distribution}*: The distribution upon which your live system will be based. This can differ from the distribution of your host system. +[28][para] +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently codenamed $${stable}, contains the latest officially released distribution of Debian. The *{testing}* distribution, temporarily codenamed $${testing}, is the staging area for the next *{stable}* release. A major advantage of using this distribution is that it has more recent versions of software relative to the *{stable}* release. The *{unstable}* distribution, permanently codenamed sid, is where active development of Debian occurs. Generally, this distribution is run by developers and those who like to live on the edge. Throughout the manual, we tend to use codenames for the releases, such as $${testing} or sid, as that is what is supported by the tools themselves. +[29][heading] +Authors +[30][para] +A list of authors (in alphabetical order): +[31][para] +_* Ben Armstrong +[32][para] +_* Brendan Sleight +[33][para] +_* Carlos Zuferri +[34][para] +_* Chris Lamb +[35][para] +_* Daniel Baumann +[36][para] +_* Franklin Piat +[37][para] +_* Jonas Stein +[38][para] +_* Kai Hendry +[39][para] +_* Marco Amadori +[40][para] +_* Mathieu Geli +[41][para] +_* Matthias Kirschner +[42][para] +_* Richard Nelson +[43][para] +_* Trent W. Buck +[44][heading] +Contributing to this document +[45][para] +This manual is intended as a community project and all proposals for improvements and contributions are extremely welcome. Please see the section {Contributing to the project}#contributing-to-project for detailed information on how to fetch the commit key and make good commits. +[46][heading] +Applying changes +[47][para] +In order to make changes to the English manual you have to edit the right files in #{manual/en/}# but prior to the submission of your contribution, please preview your work. To preview the live-manual, ensure the packages needed for building it are installed by executing: +[48][code] + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + + +[49][para] +You may build the live-manual from the top level directory of your Git checkout by executing: +[50][code] + + $$ make build + + +[51][para] +Since it takes a while to build the manual in all supported languages, authors may find it convenient to use one of the fast proofing shortcuts when reviewing the new documentation they have added to the English manual. Using #{PROOF=1}# builds live-manual in html format, but without the segmented html files, and using #{PROOF=2}# builds live-manual in pdf format, but only the A4 and letter portraits. That is why using either of the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: +[52][code] + + $$ make build PROOF=1 + + +[53][para] +When proofing one of the translations it is possible to build only one language by executing, e.g: +[54][code] + + $$ make build LANGUAGES=de + + +[55][para] +It is also possible to build by document type, e.g: +[56][code] + + $$ make build FORMATS=pdf + + +[57][para] +Or combine both, e.g: +[58][code] + + $$ make build LANGUAGES=de FORMATS=html + + +[59][para] +After revising your work and making sure that everything is fine, do not use #{make commit}# unless you are updating translations in the commit, and in that case, do not mix changes to the English manual and translations in the same commit, but use separate commits for each. See the {Translation}#translation section for more details. +[60][heading] +Translation +[61][para] +In order to translate live-manual, follow these steps depending on whether you are starting a translation from scratch or continue working on an already existing one: +[62][para] +_* Start a new translation from scratch +[63][para] +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and *{index.html.in.pot}* files in #{manual/pot/}# to your language with your favourite editor (such as /{poedit}/) and send the translated #{.po}# files to the mailing list to check their integrity. live-manual's integrity check not only ensures that the #{.po}# files are 100% translated but it also detects possible errors. +[64][para] +_2* Once checked, to enable a new language in the autobuild it is enough to add the initial translated files to #{manual/po/$${LANGUAGE}/}# and run #{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the name of the language and its name in English between brackets. +[65][para] +_* Continue with an already started translation +[66][para] +_2* If your target language has already been added, you can randomly continue translating the remaining .po files in #{manual/po/$${LANGUAGE}/}# using your favourite editor (such as /{poedit}/). +[67][para] +_2* Do not forget that you need to run #{make commit}# to ensure that the translated manuals are updated from the .po files and then you can review your changes launching #{make build}# before #{git add .}#, #{git commit -m "Translating..."}# and #{git push}#. Remember that since #{make build}# can take a considerable amount of time, you can proofread languages individually as explained in {Applying changes}#applying-changes +[68][para] +After running #{make commit}# you will see some text scroll by. These are basically informative messages about the processing status and also some hints about what can be done in order to improve live-manual. Unless you see a fatal error, you usually can proceed and submit your contribution. +[69][para] +live-manual comes with two utilities that can greatly help translators to find untranslated and changed strings. The first one is "make translate". It launches an script that tells you in detail how many untranslated strings there are in each .po file. The second one, the "make fixfuzzy" target, only acts upon changed strings but it helps you to find and fix them one by one. +[70][para] +Keep in mind that even though these utilities might be really helpful to do translation work on the command line, the use of an specialized tool like /{poedit}/ is the recommended way to do the task. It is also a good idea to read the Debian localization (l10n) documentation and, specifically to live-manual, the {Guidelines for translators}#guidelines-translators. +[71][para] +*{Note:}* You can use #{make clean}# to clean your git tree before pushing. This step is not compulsory thanks to the .gitignore file but it is a good practice to avoid committing files involuntarily. +[72][heading] +About the $${project} +[73][heading] +About the $${project} +[74][heading] +Motivation +[75][heading] +What is wrong with current live systems +[76][para] +When $${project} was initiated, there were already several Debian based live systems available and they are doing a great job. From the Debian perspective most of them have one or more of the following disadvantages: +[77][para] +_* They are not Debian projects and therefore lack support from within Debian. +[78][para] +_* They mix different distributions, e.g. *{testing}* and *{unstable}*. +[79][para] +_* They support i386 only. +[80][para] +_* They modify the behaviour and/or appearance of packages by stripping them down to save space. +[81][para] +_* They include packages from outside of the Debian archive. +[82][para] +_* They ship custom kernels with additional patches that are not part of Debian. +[83][para] +_* They are large and slow due to their sheer size and thus not suitable for rescue issues. +[84][para] +_* They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images. +[85][heading] +Why create our own live system? +[86][para] +Debian is the Universal Operating System: Debian has a live system to show around and to accurately represent the Debian system with the following main advantages: +[87][para] +_* It is a subproject of Debian. +[88][para] +_* It reflects the (current) state of one distribution. +[89][para] +_* It runs on as many architectures as possible. +[90][para] +_* It consists of unchanged Debian packages only. +[91][para] +_* It does not contain any packages that are not in the Debian archive. +[92][para] +_* It uses an unaltered Debian kernel with no additional patches. +[93][heading] +Philosophy +[94][heading] +Only unchanged packages from Debian "main" +[95][para] +We will only use packages from the Debian repository in the "main" section. The non-free section is not part of Debian and therefore cannot be used for official live system images. +[96][para] +We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian. +[97][para] +As an exception, our own packages such as live-boot, live-build or live-config may temporarily be used from our own repository for development reasons (e.g. to create development snapshots). They will be uploaded to Debian on a regular basis. +[98][heading] +No package configuration of the live system +[99][para] +In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian. +[100][para] +Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian. +[101][para] +A system for configuring packages is provided using debconf allowing custom configured packages to be installed in your custom produced live system images, but for the {prebuilt live images}#downloading-prebuilt-images we choose to leave packages in their default configuration, unless absolutely necessary in order to work in the live environment. Wherever possible, we prefer to adapt packages within the Debian archive to work better in a live system versus making changes to the live toolchain or {prebuilt image configurations}#clone-configuration-via-git. For more information, please see {Customization overview}#customization-overview. +[102][heading] +Contact +[103][para] +_* *{Mailing list}*: The primary contact for the project is the mailing list at https://lists.debian.org/debian-live/. You can email the list directly by addressing your mail to debian-live@lists.debian.org. The list archives are available at https://lists.debian.org/debian-live/. +[104][para] +_* *{IRC}*: A number of users and developers are present in the #debian-live channel on irc.debian.org (OFTC). When asking a question on IRC, please be patient for an answer. If no answer is forthcoming, please email the mailing list. +[105][para] +_* *{BTS}*: The {Debian Bug Tracking System}https://www.debian.org/Bugs/ (BTS) contains details of bugs reported by users and developers. Each bug is given a number, and is kept on file until it is marked as having been dealt with. For more information, please see {Reporting bugs}#bugs. +[106][heading] +User +[107][heading] +Installation +[108][heading] +Installation +[109][heading] +Requirements +[110][para] +Building live system images has very few system requirements: +[111][para] +_* Superuser (root) access +[112][para] +_* An up-to-date version of live-build +[113][para] +_* A POSIX-compliant shell, such as /{bash}/ or /{dash}/ +[114][para] +_* /{debootstrap}/ +[115][para] +_* Linux 2.6 or newer. +[116][para] +Note that using Debian or a Debian-derived distribution is not required - live-build will run on almost any distribution with the above requirements. +[117][heading] +Installing live-build +[118][para] +You can install live-build in a number of different ways: +[119][para] +_* From the Debian repository +[120][para] +_* From source +[121][para] +_* From snapshots +[122][para] +If you are using Debian, the recommended way is to install live-build via the Debian repository. +[123][heading] +From the Debian repository +[124][para] +Simply install live-build like any other package: +[125][code] + + # apt-get install live-build + + +[126][heading] +From source +[127][para] +live-build is developed using the Git version control system. On Debian based systems, this is provided by the /{git}/ package. To check out the latest code, execute: +[128][code] + + $$ git clone git://live-systems.org/git/live-build.git + + +[129][para] +You can build and install your own Debian package by executing: +[130][code] + + $$ cd live-build + $$ dpkg-buildpackage -b -uc -us + $$ cd .. + + +[131][para] +Now install whichever of the freshly built #{.deb}# files you were interested in, e.g. +[132][code] + + # dpkg -i live-build_4.0-1_all.deb + + +[133][para] +You can also install live-build directly to your system by executing: +[134][code] + + # make install + + +[135][para] +and uninstall it with: +[136][code] + + # make uninstall + + +[137][heading] +From 'snapshots' +[138][para] +If you do not wish to build or install live-build from source, you can use snapshots. These are built automatically from the latest version in Git and are available on http://live-systems.org/debian/. +[139][heading] +Installing live-boot and live-config +[140][para] +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. +[141][heading] +From the Debian repository +[142][para] +Both live-boot and live-config are available from the Debian repository as per {Installing live-build}#installing-live-build. +[143][heading] +From source +[144][para] +To use the latest source from git, you can follow the process below. Please ensure you are familiar with the terms mentioned in {Terms}#terms. +[145][para] +_* Checkout the live-boot and live-config sources +[146][code] + + $$ git clone git://live-systems.org/git/live-boot.git + $$ git clone git://live-systems.org/git/live-config.git + + +[147][para] +Consult the live-boot and live-config man pages for details on customizing if that is your reason for building these packages from source. +[148][para] +_* Build live-boot and live-config .deb files +[149][para] +You must build either on your target distribution or in a chroot containing your target platform: this means if your target is $${testing} then you should build against $${testing}. +[150][para] +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to build live-boot for a target distribution that differs from your build system. For example, for $${testing} live images, build live-boot in a $${testing} chroot. If your target distribution happens to match your build system distribution, you may build directly on the build system using #{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): +[151][code] + + $$ cd live-boot + $$ dpkg-buildpackage -b -uc -us + $$ cd ../live-config + $$ dpkg-buildpackage -b -uc -us + + +[152][para] +_* Use applicable generated .deb files +[153][para] +As live-boot and live-config are installed by live-build system, installing the packages in the host system is not sufficient: you should treat the generated .deb files like any other custom packages. Since your purpose for building from source is likely to test new things over the short term before the official release, follow {Installing modified or third-party packages}#installing-modified-or-third-party-packages to temporarily include the relevant files in your configuration. In particular, notice that both packages are divided into a generic part, a documentation part and one or more back-ends. Include the generic part, only one back-end matching your configuration, and optionally the documentation. Assuming you are building a live image in the current directory and have generated all .deb files for a single version of both packages in the directory above, these bash commands would copy all of the relevant packages including default back-ends: +[154][code] + + $$ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $$ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + + +[155][heading] +From 'snapshots' +[156][para] +You can let live-build automatically use the latest snapshots of live-boot and live-config by configuring the package repository on live-systems.org as a third-party repository in your live-build configuration directory. +[157][heading] +The basics +[158][heading] +The basics +[159][para] +This chapter contains a brief overview of the build process and instructions for using the three most commonly used image types. The most versatile image type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or USB portable storage device. In certain special cases, as explained later, the #{hdd}# type may be more suitable. The chapter includes detailed instructions for building and using a #{netboot}# type image, which is a bit more involved due to the setup required on the server. This is an slightly advanced topic for anyone who is not already familiar with netbooting, but it is included here because once the setup is done, it is a very convenient way to test and deploy images for booting on the local network without the hassle of dealing with image media. +[160][para] +The section finishes with a quick introduction to {webbooting}#webbooting which is, perhaps, the easiest way of using different images for different purposes, switching from one to the other as needed using the internet as a means. +[161][para] +Throughout the chapter, we will often refer to the default filenames produced by live-build. If you are {downloading a prebuilt image}#downloading-prebuilt-images instead, the actual filenames may vary. +[162][heading] +What is a live system? +[163][para] +A live system usually means an operating system booted on a computer from a removable medium, such as a CD-ROM or USB stick, or from a network, ready to use without any installation on the usual drive(s), with auto-configuration done at run time (see {Terms}#terms). +[164][para] +With live systems, it's an operating system, built for one of the supported architectures (currently amd64 and i386). It is made from the following parts: +[165][para] +_* *{Linux kernel image}*, usually named #{vmlinuz*}# +[166][para] +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux boot, containing modules possibly needed to mount the System image and some scripts to do it. +[167][para] +_* *{System image}*: The operating system's filesystem image. Usually, a SquashFS compressed filesystem is used to minimize the live system image size. Note that it is read-only. So, during boot the live system will use a RAM disk and 'union' mechanism to enable writing files within the running system. However, all modifications will be lost upon shutdown unless optional persistence is used (see {Persistence}#persistence). +[168][para] +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen medium, possibly presenting a prompt or menu to allow selection of options/configuration. It loads the Linux kernel and its initrd to run with an associated system filesystem. Different solutions can be used, depending on the target medium and format of the filesystem containing the previously mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, extlinux for ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 partitions, etc. +[169][para] +You can use live-build to build the system image from your specifications, set up a Linux kernel, its initrd, and a bootloader to run them, all in one medium-dependant format (ISO9660 image, disk image, etc.). +[170][heading] +Downloading prebuilt images +[171][para] +While the focus of this manual is developing and building your own live images, you may simply wish to try one of our prebuilt images, either as an introduction to their use or instead of building your own. These images are built using our {live-images git repository}#clone-configuration-via-git and official stable releases are published at https://www.debian.org/CD/live/. In addition, older and upcoming releases, and unofficial images containing non-free firmware and drivers are available at http://live-systems.org/cdimage/release/. +[172][heading] +Using the web live image builder +[173][para] +As a service to the community, we run a web-based live image builder service at http://live-systems.org/build/. This site is maintained on a best effort basis. That is, although we strive to keep it up-to-date and operational at all times, and do issue notices for significant operational outages, we cannot guarantee 100% availability or fast image building, and the service may occasionally have issues that take some time to resolve. If you have problems or questions about the service, please {contact us}#contact, providing us with the link to your build. +[174][heading] +Web builder usage and caveats +[175][para] +The web interface currently makes no provision to prevent the use of invalid combinations of options, and in particular, where changing an option would normally (i.e. using live-build directly) change defaults of other options listed in the web form, the web builder does not change these defaults. Most notably, if you change #{--architectures}# from the default #{i386}# to #{amd64}#, you must change the corresponding option #{--linux-flavours}# from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for the version of live-build installed on the web builder for more details. The version number of live-build is listed at the bottom of the web builder page. +[176][para] +The time estimate given by the web builder is a crude estimate only and may not reflect how long your build actually takes. Nor is the estimate updated once it is displayed. Please be patient. Do not refresh the page you land on after submitting the build, as this will resubmit a new build with the same parameters. You should {contact us}#contact if you don't receive notification of your build only once you are certain you've waited long enough and verified the notification e-mail did not get caught by your own e-mail spam filter. +[177][para] +The web builder is limited in the kinds of images it can build. This keeps it simple and efficient to use and maintain. If you would like to make customizations that are not provided for by the web interface, the rest of this manual explains how to build your own images using live-build. +[178][heading] +First steps: building an ISO hybrid image +[179][para] +Regardless of the image type, you will need to perform the same basic steps to build an image each time. As a first example, create a build directory, change to that directory and then execute the following sequence of live-build commands to create a basic ISO hybrid image containing a default live system without X.org. It is suitable for burning to CD or DVD media, and also to copy onto a USB stick. +[180][para] +The name of the working directory is absolutely up to you, but if you take a look at the examples used throughout live-manual, it is a good idea to use a name that helps you identify the image you are working with in each directory, especially if you are working or experimenting with different image types. In this case you are going to build a default system so let's call it, for example, live-default. +[181][code] + + $$ mkdir live-default && cd live-default + + +[182][para] +Then, run the #{lb config}# command. This will create a "config/" hierarchy in the current directory for use by other commands: +[183][code] + + $$ lb config + + +[184][para] +No parameters are passed to these commands, so defaults for all of their various options will be used. See {The lb config command}#lb-config for more details. +[185][para] +Now that the "config/" hierarchy exists, build the image with the #{lb build}# command: +[186][code] + + # lb build + + +[187][para] +This process can take a while, depending on the speed of your computer and your network connection. When it is complete, there should be a #{live-image-i386.hybrid.iso}# image file, ready to use, in the current directory. +[188][para] +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. +[189][heading] +Using an ISO hybrid live image +[190][para] +After either building or downloading an ISO hybrid image, which can be obtained at https://www.debian.org/CD/live/, the usual next step is to prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or a USB stick. +[191][heading] +Burning an ISO image to a physical medium +[192][para] +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the command-line to burn the image. For instance: +[193][code] + + # apt-get install xorriso + $$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + + +[194][heading] +Copying an ISO hybrid image to a USB stick +[195][para] +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick with the #{cp}# program or an equivalent. Plug in a USB stick with a size large enough for your image file and determine which device it is, which we hereafter refer to as #{$${USBSTICK}}#. This is the device file of your key, such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find the right device name by looking in #{dmesg}#'s output after plugging in the stick, or better yet, #{ls -l /dev/disk/by-id}#. +[196][para] +Once you are certain you have the correct device name, use the #{cp}# command to copy the image to the stick.*{This will definitely overwrite any previous contents on your stick!}* +[197][code] + + $$ cp live-image-i386.hybrid.iso $${USBSTICK} + $$ sync + + +[198][para] +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. +[199][heading] +Using the space left on a USB stick +[200][para] +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first partition on the device will be filled up by the live system. To use the remaining free space, use a partitioning tool such as /{gparted}/ or /{parted}/ to create a new partition on the stick. +[201][code] + + # gparted $${USBSTICK} + + +[202][para] +After the partition is created, where #{$${PARTITION}}# is the name of the partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One possible choice would be ext4. +[203][code] + + # mkfs.ext4 $${PARTITION} + + +[204][para] +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. +[205][para] +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* +[206][heading] +Booting the live medium +[207][para] +The first time you boot your live medium, whether CD, DVD, USB key, or PXE boot, some setup in your computer's BIOS may be needed first. Since BIOSes vary greatly in features and key bindings, we cannot get into the topic in depth here. Some BIOSes provide a key to bring up a menu of boot devices at boot time, which is the easiest way if it is available on your system. Otherwise, you need to enter the BIOS configuration menu and change the boot order to place the boot device for the live system before your normal boot device. +[208][para] +Once you've booted the medium, you are presented with a boot menu. If you just press enter here, the system will boot using the default entry, #{Live}# and default options. For more information about boot options, see the "help" entry in the menu and also the live-boot and live-config man pages found within the live system. +[209][para] +Assuming you've selected #{Live}# and booted a default desktop live image, after the boot messages scroll by, you should be automatically logged into the #{user}# account and see a desktop, ready to use. If you have booted a console-only image, such as a #{standard}# flavour {prebuilt image}#downloading-prebuilt-images, you should be automatically logged in on the console to the #{user}# account and see a shell prompt, ready to use. +[210][heading] +Using a virtual machine for testing +[211][para] +It can be a great time-saver for the development of live images to run them in a virtual machine (VM). This is not without its caveats: +[212][para] +_* Running a VM requires enough RAM for both the guest OS and the host and a CPU with hardware support for virtualization is recommended. +[213][para] +_* There are some inherent limitations to running on a VM, e.g. poor video performance, limited choice of emulated hardware. +[214][para] +_* When developing for specific hardware, there is no substitute for running on the hardware itself. +[215][para] +_* Occasionally there are bugs that relate only to running in a VM. When in doubt, test your image directly on the hardware. +[216][para] +Provided you can work within these constraints, survey the available VM software and choose one that is suitable for your needs. +[217][heading] +Testing an ISO image with QEMU +[218][para] +The most versatile VM in Debian is QEMU. If your processor has hardware support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ package description briefly lists the requirements. +[219][para] +First, install /{qemu-kvm}/ if your processor supports it. If not, install /{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in the following examples. The /{qemu-utils}/ package is also valuable for creating virtual disk images with #{qemu-img}#. +[220][code] + + # apt-get install qemu-kvm qemu-utils + + +[221][para] +Booting an ISO image is simple: +[222][code] + + $$ kvm -cdrom live-image-i386.hybrid.iso + + +[223][para] +See the man pages for more details. +[224][heading] +Testing an ISO image with VirtualBox +[225][para] +In order to test the ISO with /{virtualbox}/: +[226][code] + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $$ virtualbox + + +[227][para] +Create a new virtual machine, change the storage settings to use #{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. +[228][para] +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. +[229][code] + + $$ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + + +[230][para] +In order to make the dkms package work, also the kernel headers for the kernel flavour used in your image need to be installed. Instead of manually listing the correct /{linux-headers}/ package in above created package list, the selection of the right package can be done automatically by live-build. +[231][code] + + $$ lb config --linux-packages "linux-image linux-headers" + + +[232][heading] +Building and using an HDD image +[233][para] +Building an HDD image is similar to an ISO hybrid one in all respects except you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# which cannot be burnt to optical media. It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices. Normally, an ISO hybrid image can be used for this purpose instead, but if you have a BIOS which does not handle hybrid images properly, you need an HDD image. +[234][para] +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): +[235][code] + + # lb clean --binary + + +[236][para] +Run the #{lb config}# command as before, except this time specifying the HDD image type: +[237][code] + + $$ lb config -b hdd + + +[238][para] +Now build the image with the #{lb build}# command: +[239][code] + + # lb build + + +[240][para] +When the build finishes, a #{live-image-i386.img}# file should be present in the current directory. +[241][para] +The generated binary image contains a VFAT partition and the syslinux bootloader, ready to be directly written on a USB device. Once again, using an HDD image is just like using an ISO hybrid one on USB. Follow the instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except use the filename #{live-image-i386.img}# instead of #{live-image-i386.hybrid.iso}#. +[242][para] +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run #{kvm}# or #{qemu}#, depending on which version your host system needs, specifying #{live-image-i386.img}# as the first hard drive. +[243][code] + + $$ kvm -hda live-image-i386.img + + +[244][heading] +Building a netboot image +[245][para] +The following sequence of commands will create a basic netboot image containing a default live system without X.org. It is suitable for booting over the network. +[246][para] +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: +[247][code] + + # lb clean + + +[248][para] +In this specific case, a #{lb clean --binary}# would not be enough to clean up the necessary stages. The cause for this is that in netboot setups, a different initramfs configuration needs to be used which live-build performs automatically when building netboot images. Since the initramfs creation belongs to the chroot stage, switching to netboot in an existing build directory means to rebuild the chroot stage too. Therefore, #{lb clean}# (which will remove the chroot stage, too) needs to be used. +[249][para] +Run the #{lb config}# command as follows to configure your image for netbooting: +[250][code] + + $$ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + + +[251][para] +In contrast with the ISO and HDD images, netbooting does not, itself, serve the filesystem image to the client, so the files must be served via NFS. Different network filesystems can be chosen through lb config. The #{--net-root-path}# and #{--net-root-server}# options specify the location and server, respectively, of the NFS server where the filesystem image will be located at boot time. Make sure these are set to suitable values for your network and server. +[252][para] +Now build the image with the #{lb build}# command: +[253][code] + + # lb build + + +[254][para] +In a network boot, the client runs a small piece of software which usually resides on the EPROM of the Ethernet card. This program sends a DHCP request to get an IP address and information about what to do next. Typically, the next step is getting a higher level bootloader via the TFTP protocol. That could be pxelinux, GRUB, or even boot directly to an operating system like Linux. +[255][para] +For example, if you unpack the generated #{live-image-i386.netboot.tar}# archive in the #{/srv/debian-live}# directory, you'll find the filesystem image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux bootloader in #{tftpboot/}#. +[256][para] +We must now configure three services on the server to enable netbooting: the DHCP server, the TFTP server and the NFS server. +[257][heading] +DHCP server +[258][para] +We must configure our network's DHCP server to be sure to give an IP address to the netbooting client system, and to advertise the location of the PXE bootloader. +[259][para] +Here is an example for inspiration, written for the ISC DHCP server #{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: +[260][code] + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + + +[261][heading] +TFTP server +[262][para] +This serves the kernel and initial ramdisk to the system at run time. +[263][para] +You should install the /{tftpd-hpa}/ package. It can serve all files contained inside a root directory, usually #{/srv/tftp}#. To let it serve files inside #{/srv/debian-live/tftpboot}#, run as root the following command: +[264][code] + + # dpkg-reconfigure -plow tftpd-hpa + + +[265][para] +and fill in the new tftp server directory when being asked about it. +[266][heading] +NFS server +[267][para] +Once the guest computer has downloaded and booted a Linux kernel and loaded its initrd, it will try to mount the Live filesystem image through a NFS server. +[268][para] +You need to install the /{nfs-kernel-server}/ package. +[269][para] +Then, make the filesystem image available through NFS by adding a line like the following to #{/etc/exports}#: +[270][code] + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + + +[271][para] +and tell the NFS server about this new export with the following command: +[272][code] + + # exportfs -rv + + +[273][para] +Setting up these three services can be a little tricky. You might need some patience to get all of them working together. For more information, see the syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the Debian Installer Manual's TFTP Net Booting section at http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, as their processes are very similar. +[274][heading] +Netboot testing HowTo +[275][para] +Netboot image creation is made easy with live-build, but testing the images on physical machines can be really time consuming. +[276][para] +To make our life easier, we can use virtualization. +[277][heading] +Qemu +[278][para] +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. +[279][para] +Edit #{/etc/qemu-ifup}#: +[280][code] + + #!/bin/sh + sudo -p "Password for $$0:" /sbin/ifconfig $$1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $$1 for bridged mode..." + sudo /sbin/ifconfig $$1 0.0.0.0 promisc up + echo "Adding $$1 to br0..." + sudo /usr/sbin/brctl addif br0 $$1 + sleep 2 + + +[281][para] +Get, or build a #{grub-floppy-netboot}#. +[282][para] +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" +[283][heading] +Webbooting +[284][para] +Webbooting is a convenient way of retrieving and booting live systems using the internet as a means. The requirements for webbooting are very few. On the one hand, you need a medium with a bootloader, an initial ramdisk and a kernel. On the other hand, a web server to store the squashfs files which contain the filesystem. +[285][heading] +Getting the webboot files +[286][para] +As usual, you can build the images yourself or use the prebuilt files, which are available on the project's homepage at http://live-systems.org/. Using prebuilt images would be handy for doing initial testing until one can fine tune their own needs. If you have built a live image you will find the files needed for webbooting in the build directory under #{binary/live/}#. The files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. +[287][para] +It is also possible to extract those files from an already existing iso image. In order to achieve that, loopback mount the image as follows: +[288][code] + + # mount -o loop image.iso /mnt + + +[289][para] +The files are to be found under the #{live/}# directory. In this specific case, it would be #{/mnt/live/}#. This method has the disadvantage that you need to be root to be able to mount the image. However, it has the advantage that it is easily scriptable and thus, easily automatized. +[290][para] +But undoubtedly, the easiest way of extracting the files from an iso image and uploading it to the web server at the same time, is using the midnight commander or /{mc}/. If you have the /{genisoimage}/ package installed, the two-pane file manager allows you to browse the contents of an iso file in one pane and upload the files via ftp in the other pane. Even though this method requires manual work, it does not require root privileges. +[291][heading] +Booting webboot images +[292][para] +While some users will prefer virtualization to test webbooting, we refer to real hardware here to match the following possible use case which should only be considered as an example. +[293][para] +In order to boot a webboot image it is enough to have the components mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a directory named #{live/}# and install syslinux as bootloader. Then boot from the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot options. live-boot will retrieve the squashfs file and store it into ram. This way, it is possible to use the downloaded compressed filesystem as a regular live system. For example: +[294][code] + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + + +[295][para] +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. +[296][heading] +Overview of tools +[297][heading] +Overview of tools +[298][para] +This chapter contains an overview of the three main tools used in building live systems: live-build, live-boot and live-config. +[299][heading] +The live-build package +[300][para] +live-build is a collection of scripts to build live systems. These scripts are also referred to as "commands". +[301][para] +The idea behind live-build is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image. +[302][para] +Many concepts are similar to those used to build Debian packages with /{debhelper}/: +[303][para] +_* The scripts have a central location for configuring their operation. In /{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For example, dh_install will look, among others, for a file called #{debian/install}# to determine which files should exist in a particular binary package. In much the same way, live-build stores its configuration entirely under a #{config/}# subdirectory. +[304][para] +_* The scripts are independent - that is to say, it is always safe to run each command. +[305][para] +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton configuration directory. This could be considered to be similar to tools such as /{dh-make}/. For more information about these tools, read on, since the remainder of this section discuses the four most important commands. Note that the preceding #{lb}# is a generic wrapper for live-build commands. +[306][para] +_* *{lb config}*: Responsible for initializing a Live system configuration directory. See {The lb config command}#lb-config for more information. +[307][para] +_* *{lb build}*: Responsible for starting a Live system build. See {The lb build command}#lb-build for more information. +[308][para] +_* *{lb clean}*: Responsible for removing parts of a Live system build. See {The lb clean command}#lb-clean for more information. +[309][heading] +The #{lb config}# command +[310][para] +As discussed in {live-build}#live-build, the scripts that make up live-build read their configuration with the #{source}# command from a single directory named #{config/}#. As constructing this directory by hand would be time-consuming and error-prone, the #{lb config}# command can be used to create the initial skeleton configuration tree. +[311][para] +Issuing #{lb config}# without any arguments creates the #{config/}# subdirectory which is populated with some default settings in configuration files, and two skeleton trees named #{auto/}# and #{local/}#. +[312][code] + + $$ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + + +[313][para] +Using #{lb config}# without any arguments would be suitable for users who need a very basic image, or who intend to provide a more complete configuration via #{auto/config}# later (see {Managing a configuration}#managing-a-configuration for details). +[314][para] +Normally, you will want to specify some options. For example, to specify which package manager to use while building the image: +[315][code] + + $$ lb config --apt aptitude + + +[316][para] +It is possible to specify many options, such as: +[317][code] + + $$ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + + +[318][para] +A full list of options is available in the #{lb_config}# man page. +[319][heading] +The #{lb build}# command +[320][para] +The #{lb build}# command reads in your configuration from the #{config/}# directory. It then runs the lower level commands needed to build your Live system. +[321][heading] +The #{lb clean}# command +[322][para] +It is the job of the #{lb clean}# command to remove various parts of a build so subsequent builds can start from a clean state. By default, #{chroot}#, #{binary}# and #{source}# stages are cleaned, but the cache is left intact. Also, individual stages can be cleaned. For example, if you have made changes that only affect the binary stage, use #{lb clean --binary}# prior to building a new binary. If your changes invalidate the bootstrap and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or #{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man page for a full list of options. +[323][heading] +The live-boot package +[324][para] +live-boot is a collection of scripts providing hooks for the /{initramfs-tools}/, used to generate an initramfs capable of booting live systems, such as those created by live-build. This includes the live system ISOs, netboot tarballs, and USB stick images. +[325][para] +At boot time it will look for read-only media containing a #{/live/}# directory where a root filesystem (often a compressed filesystem image like squashfs) is stored. If found, it will create a writable environment, using aufs, for Debian like systems to boot from. +[326][para] +More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter on initramfs. +[327][heading] +The live-config package +[328][para] +live-config consists of the scripts that run at boot time after live-boot to configure the live system automatically. It handles such tasks as setting the hostname, locales and timezone, creating the live user, inhibiting cron jobs and performing autologin of the live user. +[329][heading] +Managing a configuration +[330][heading] +Managing a configuration +[331][para] +This chapter explains how to manage a live configuration from initial creation, through successive revisions and successive releases of both the live-build software and the live image itself. +[332][heading] +Dealing with configuration changes +[333][para] +Live configurations rarely are perfect on the first try. It may be fine to pass #{lb config}# options from the command-line to perform a single build, but it is more typical to revise those options and build again until you are satisfied. To support these changes, you will need auto scripts which ensure your configuration is kept in a consistent state. +[334][heading] +Why use auto scripts? What do they do? +[335][para] +The #{lb config}# command stores the options you pass to it in #{config/*}# files along with many other options set to default values. If you run #{lb config}# again, it will not reset any option that was defaulted based on your initial options. So, for example, if you run #{lb config}# again with a new value for #{--binary-images}#, any dependent options that were defaulted for the old image type may no longer work with the new ones. Nor are these files intended to be read or edited. They store values for over a hundred options, so nobody, let alone yourself, will be able to see in these which options you actually specified. And finally, if you run #{lb config}#, then upgrade live-build and it happens to rename an option, #{config/*}# would still contain variables named after the old option that are no longer valid. +[336][para] +For all these reasons, #{auto/*}# scripts will make your life easier. They are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# commands that are designed to help you manage your configuration. The #{auto/config}# script stores your #{lb config}# command with all desired options, the #{auto/clean}# script removes the files containing configuration variable values, and the #{auto/build}# script keeps a #{build.log}# of each build. Each of these scripts is run automatically every time you run the corresponding #{lb}# command. By using these scripts, your configuration is easier to read and is kept internally consistent from one revision to the next. Also, it will be much easier for you identify and fix options which need to change when you upgrade live-build after reading the updated documentation. +[337][heading] +Use example auto scripts +[338][para] +For your convenience, live-build comes with example auto shell scripts to copy and edit. Start a new, default configuration, then copy the examples into it: +[339][code] + + $$ mkdir mylive && cd mylive && lb config + $$ mkdir auto + $$ cp /usr/share/doc/live-build/examples/auto/* auto/ + + +[340][para] +Edit #{auto/config}#, adding any options as you see fit. For instance: +[341][code] + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "$${@}" + + +[342][para] +Now, each time you use #{lb config}#, #{auto/config}# will reset the configuration based on these options. When you want to make changes to them, edit the options in this file instead of passing them to #{lb config}#. When you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files along with any other build products. And finally, when you use #{lb build}#, a log of the build will be written by #{auto/build}# in #{build.log}#. +[343][para] +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. +[344][heading] +Clone a configuration published via Git +[345][para] +Use the #{lb config --config}# option to clone a Git repository that contains a live system configuration. If you would like to base your configuration on one maintained by the $${project}, look at http://live-systems.org/gitweb/ for the repository named #{live-images}# in the category #{Packages}#. This repository contains the configurations for the live systems {prebuilt images}#downloading-prebuilt-images. +[346][para] +For example, to build a standard image, use the #{live-images}# repository as follows: +[347][code] + + $$ mkdir live-images && cd live-images + $$ lb config --config git://live-systems.org/git/live-images.git + $$ cd images/standard + + +[348][para] +Edit #{auto/config}# and any other things you need in the #{config}# tree to suit your needs. For example, the unofficial non-free prebuilt images are made by simply adding #{--archive-areas "main contrib non-free"}#. +[349][para] +You may optionally define a shortcut in your Git configuration by adding the following to your #{$${HOME}/.gitconfig}#: +[350][code] + + [url "git://live-systems.org/git/"] + insteadOf = lso: + + +[351][para] +This enables you to use #{lso:}# anywhere you need to specify the address of a #{live-systems.org}# git repository. If you also drop the optional #{.git}# suffix, starting a new image using this configuration is as easy as: +[352][code] + + $$ lb config --config lso:live-images + + +[353][para] +Cloning the entire #{live-images}# repository pulls the configurations used for several images. If you feel like building a different image after you have finished with the first one, change to another directory and again and optionally, make any changes to suit your needs. +[354][para] +In any case, remember that every time you will have to build the image as superuser: #{lb build}# +[355][heading] +Customizing contents +[356][heading] +Customization overview +[357][para] +This chapter gives an overview of the various ways in which you may customize a live system. +[358][heading] +Build time vs. boot time configuration +[359][para] +Live system configuration options are divided into build-time options which are options that are applied at build time and boot-time options which are applied at boot time. Boot-time options are further divided into those occurring early in the boot, applied by the live-boot package, and those that happen later in the boot, applied by live-config. Any boot-time option may be modified by the user by specifying it at the boot prompt. The image may also be built with default boot parameters so users can normally just boot directly to the live system without specifying any options when all of the defaults are suitable. In particular, the argument to #{lb --bootappend-live}# consists of any default kernel command line options for the Live system, such as persistence, keyboard layouts, or timezone. See {Customizing locale and language}#customizing-locale-and-language, for example. +[360][para] +Build-time configuration options are described in the #{lb config}# man page. Boot-time options are described in the man pages for live-boot and live-config. Although the live-boot and live-config packages are installed within the live system you are building, it is recommended that you also install them on your build system for easy reference when you are working on your configuration. It is safe to do so, as none of the scripts contained within them are executed unless the system is configured as a live system. +[361][heading] +Stages of the build +[362][para] +The build process is divided into stages, with various customizations applied in sequence in each. The first stage to run is the *{bootstrap}* stage. This is the initial phase of populating the chroot directory with packages to make a barebones Debian system. This is followed by the *{chroot}* stage, which completes the construction of chroot directory, populating it with all of the packages listed in the configuration, along with any other materials. Most customization of content occurs in this stage. The final stage of preparing the live image is the *{binary}* stage, which builds a bootable image, using the contents of the chroot directory to construct the root filesystem for the Live system, and including the installer and any other additional material on the target medium outside of the Live system's filesystem. After the live image is built, if enabled, the source tarball is built in the *{source}* stage. +[363][para] +Within each of these stages, there is a particular sequence in which commands are applied. These are arranged in such a way as to ensure customizations can be layered in a reasonable fashion. For example, within the *{chroot}* stage, preseeds are applied before any packages are installed, packages are installed before any locally included files are copied, and hooks are run later, after all of the materials are in place. +[364][heading] +Supplement lb config with files +[365][para] +Although #{lb config}# creates a skeletal configuration in the #{config/}# directory, to accomplish your goals, you may need to provide additional files in subdirectories of #{config/}#. Depending on where the files are stored in the configuration, they may be copied into the live system's filesystem or into the binary image filesystem, or may provide build-time configurations of the system that would be cumbersome to pass as command-line options. You may include things such as custom lists of packages, custom artwork, or hook scripts to run either at build time or at boot time, boosting the already considerable flexibility of debian-live with code of your own. +[366][heading] +Customization tasks +[367][para] +The following chapters are organized by the kinds of customization task users typically perform: {Customizing package installation}#customizing-package-installation, {Customizing contents}#customizing-contents and {Customizing locale and language}#customizing-locale-and-language cover just a few of the things you might want to do. +[368][heading] +Customizing package installation +[369][heading] +Customizing package installation +[370][para] +Perhaps the most basic customization of a live system is the selection of packages to be included in the image. This chapter guides you through the various build-time options to customize live-build's installation of packages. The broadest choices influencing which packages are available to install in the image are the distribution and archive areas. To ensure decent download speeds, you should choose a nearby distribution mirror. You can also add your own repositories for backports, experimental or custom packages, or include packages directly as files. You can define lists of packages, including metapackages which will install many related packages at once, such as packages for a particular desktop or language. Finally, a number of options give some control over /{apt}/, or if you prefer, /{aptitude}/, at build time when packages are installed. You may find these handy if you use a proxy, want to disable installation of recommended packages to save space, or need to control which versions of packages are installed via APT pinning, to name a few possibilities. +[371][heading] +Package sources +[372][heading] +Distribution, archive areas and mode +[373][para] +The distribution you choose has the broadest impact on which packages are available to include in your live image. Specify the codename, which defaults to $${testing} for the $${testing} version of live-build. Any current distribution carried in the archive may be specified by its codename here. (See {Terms}#terms for more details.) The #{--distribution}# option not only influences the source of packages within the archive, but also instructs live-build to behave as needed to build each supported distribution. For example, to build against the *{unstable}* release, sid, specify: +[374][code] + + $$ lb config --distribution sid + + +[375][para] +Within the distribution archive, archive areas are major divisions of the archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only #{main}# contains software that is part of the Debian distribution, hence that is the default. One or more values may be specified, e.g. +[376][code] + + $$ lb config --archive-areas "main contrib non-free" + + +[377][para] +Experimental support is available for some Debian derivatives through a #{--mode}# option. By default, this option is set to #{debian}# only if you are building on a Debian or on an unknown system. If #{lb config}# is invoked on any of the supported derivatives, it will default to create an image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, the distribution names and archive areas for the specified derivative are supported instead of the ones for Debian. The mode also modifies live-build behaviour to suit the derivatives. +[378][para] +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The $${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. +[379][heading] +Distribution mirrors +[380][para] +The Debian archive is replicated across a large network of mirrors around the world so that people in each region can choose a nearby mirror for best download speed. Each of the #{--mirror-*}# options governs which distribution mirror is used at various stages of the build. Recall from {Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is when the chroot is initially populated by /{debootstrap}/ with a minimal system, and the *{chroot}* stage is when the chroot used to construct the live system's filesystem is built. Thus, the corresponding mirror switches are used for those stages, and later, in the *{binary}* stage, the #{--mirror-binary}# and #{--mirror-binary-security}# values are used, superseding any mirrors used in an earlier stage. +[381][heading] +Distribution mirrors used at build time +[382][para] +To set the distribution mirrors used at build time to point at a local mirror, it is sufficient to set #{--mirror-bootstrap}# and #{--mirror-chroot-security}# as follows. +[383][code] + + $$ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + + +[384][para] +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the #{--mirror-bootstrap}# value. +[385][heading] +Distribution mirrors used at run time +[386][para] +The #{--mirror-binary*}# options govern the distribution mirrors placed in the binary image. These may be used to install additional packages while running the live system. The defaults employ #{httpredir.debian.org}#, a service that chooses a geographically close mirror based, among other things, on the user's IP family and the availability of the mirrors. This is a suitable choice when you cannot predict which mirror will be best for all of your users. Or you may specify your own values as shown in the example below. An image built from this configuration would only be suitable for users on a network where "#{mirror}#" is reachable. +[387][code] + + $$ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + + +[388][heading] +Additional repositories +[389][para] +You may add more repositories, broadening your package choices beyond what is available in your target distribution. These may be, for example, for backports, experimental or custom packages. To configure additional repositories, create #{config/archives/your-repository.list.chroot}#, and/or #{config/archives/your-repository.list.binary}# files. As with the #{--mirror-*}# options, these govern the repositories used in the *{chroot}* stage when building the image, and in the *{binary}* stage, i.e. for use when running the live system. +[390][para] +For example, #{config/archives/live.list.chroot}# allows you to install packages from the debian-live snapshot repository at live system build time. +[391][code] + + deb http://live-systems.org/ sid-snapshots main contrib non-free + + +[392][para] +If you add the same line to #{config/archives/live.list.binary}#, the repository will be added to your live system's #{/etc/apt/sources.list.d/}# directory. +[393][para] +If such files exist, they will be picked up automatically. +[394][para] +You should also put the GPG key used to sign the repository into #{config/archives/your-repository.key.{binary,chroot}}# files. +[395][para] +Should you need custom APT pinning, such APT preferences snippets can be placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and will be automatically added to your live system's #{/etc/apt/preferences.d/}# directory. +[396][heading] +Choosing packages to install +[397][para] +There are a number of ways to choose which packages live-build will install in your image, covering a variety of different needs. You can simply name individual packages to install in a package list. You can also use metapackages in those lists, or select them using package control file fields. And finally, you may place package files in your #{config/}# tree, which is well suited to testing of new or experimental packages before they are available from a repository. +[398][heading] +Package lists +[399][para] +Package lists are a powerful way of expressing which packages should be installed. The list syntax supports conditional sections which makes it easy to build lists and adapt them for use in multiple configurations. Package names may also be injected into the list using shell helpers at build time. +[400][para] +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. +[401][heading] +Using metapackages +[402][para] +The simplest way to populate your package list is to use a task metapackage maintained by your distribution. For example: +[403][code] + + $$ lb config + $$ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + + +[404][para] +This supercedes the older predefined list method supported in #{live-build}# 2.x. Unlike predefined lists, task metapackages are not specific to the Live System project. Instead, they are maintained by specialist working groups within the distribution and therefore reflect the consensus of each group about which packages best serve the needs of the intended users. They also cover a much broader range of use cases than the predefined lists they replace. +[405][para] +All task metapackages are prefixed #{task-}#, so a quick way to determine which are available (though it may contain a handful of false hits that match the name but aren't metapackages) is to match on the package name with: +[406][code] + + $$ apt-cache search --names-only ^task- + + +[407][para] +In addition to these, you will find other metapackages with various purposes. Some are subsets of broader task packages, like #{gnome-core}#, while others are individual specialized parts of a Debian Pure Blend, such as the #{education-*}# metapackages. To list all metapackages in the archive, install the #{debtags}# package and list all packages with the #{role::metapackage}# tag as follows: +[408][code] + + $$ debtags search role::metapackage + + +[409][heading] +Local package lists +[410][para] +Whether you list metapackages, individual packages, or a combination of both, all local package lists are stored in #{config/package-lists/}#. Since more than one list can be used, this lends itself well to modular designs. For example, you may decide to devote one list to a particular choice of desktop, another to a collection of related packages that might as easily be used on top of a different desktop. This allows you to experiment with different combinations of sets of packages with a minimum of fuss, sharing common lists between different live image projects. +[411][para] +Package lists that exist in this directory need to have a #{.list}# suffix in order to be processed, and then an additional stage suffix, #{.chroot}# or #{.binary}# to indicate which stage the list is for. +[412][para] +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. +[413][heading] +Local binary package lists +[414][para] +To make a binary stage list, place a file suffixed with #{.list.binary}# in #{config/package-lists/}#. These packages are not installed in the live filesystem, but are included on the live medium under #{pool/}#. You would typically use such a list with one of the non-live installer variants. As mentioned above, if you want this list to be the same as your chroot stage list, simply use the #{.list}# suffix by itself. +[415][heading] +Generated package lists +[416][para] +It sometimes happens that the best way to compose a list is to generate it with a script. Any line starting with an exclamation point indicates a command to be executed within the chroot when the image is built. For example, one might include the line #{! grep-aptavail -n -sPackage -FPriority standard | sort}# in a package list to produce a sorted list of available packages with #{Priority: standard}#. +[417][para] +In fact, selecting packages with the #{grep-aptavail}# command (from the #{dctrl-tools}# package) is so useful that #{live-build}# provides a #{Packages}# helper script as a convenience. This script takes two arguments: #{field}# and #{pattern}#. Thus, you can create a list with the following contents: +[418][code] + + $$ lb config + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + + +[419][heading] +Using conditionals inside package lists +[420][para] +Any of the live-build configuration variables stored in #{config/*}# (minus the #{LB_}# prefix) may be used in conditional statements in package lists. Generally, this means any #{lb config}# option uppercased and with dashes changed to underscores. But in practice, it is only the ones that influence package selection that make sense, such as #{DISTRIBUTION}#, #{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. +[421][para] +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is specified: +[422][code] + + #if ARCHITECTURES amd64 + ia32-libs + #endif + + +[423][para] +You may test for any one of a number of values, e.g. to install /{memtest86+}/ if either #{--architectures i386}# or #{--architectures amd64}# is specified: +[424][code] + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + + +[425][para] +You may also test against variables that may contain more than one value, e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified via #{--archive-areas}#: +[426][code] + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + + +[427][para] +The nesting of conditionals is not supported. +[428][heading] +Removing packages at install time +[429][para] +You can list packages in files with #{.list.chroot_live}# and #{.list.chroot_install}# suffixes inside the #{config/package-lists}# directory. If both a live and an install list exist, the packages in the #{.list.chroot_live}# list are removed with a hook after the installation (if the user uses the installer). The packages in the #{.list.chroot_install}# list are present both in the live system and in the installed system. This is a special tweak for the installer and may be useful if you have #{--debian-installer live}# set in your config, and wish to remove live system-specific packages at install time. +[430][heading] +Desktop and language tasks +[431][para] +Desktop and language tasks are special cases that need some extra planning and configuration. Live images are different from Debian Installer images in this respect. In the Debian Installer, if the medium was prepared for a particular desktop environment flavour, the corresponding task will be automatically installed. Thus, there are internal #{gnome-desktop}#, #{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for tasks for languages, but the user's language choice during the install influences the selection of corresponding language tasks. +[432][para] +When developing a desktop live image, the image typically boots directly to a working desktop, the choices of both desktop and default language having been made at build time, not at run time as in the case of the Debian Installer. That's not to say that a live image couldn't be built to support multiple desktops or multiple languages and offer the user a choice, but that is not live-build's default behaviour. +[433][para] +Because there is no provision made automatically for language tasks, which include such things as language-specific fonts and input-method packages, if you want them, you need to specify them in your configuration. For example, a GNOME desktop image containing support for German might include these task metapackages: +[434][code] + + $$ lb config + $$ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $$ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + + +[435][heading] +Kernel flavour and version +[436][para] +One or more kernel flavours will be included in your image by default, depending on the architecture. You can choose different flavours via the #{--linux-flavours}# option. Each flavour is suffixed to the default stub #{linux-image}# to form each metapackage name which in turn depends on an exact kernel package to be included in your image. +[437][para] +Thus by default, an #{amd64}# architecture image will include the #{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture image will include the #{linux-image-586}# metapackage. +[438][para] +When more than one kernel package version is available in your configured archives, you can specify a different kernel package name stub with the #{--linux-packages}# option. For example, supposing you are building an #{amd64}# architecture image and add the experimental archive for testing purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# kernel. You would configure that image as follows: +[439][code] + + $$ lb config --linux-packages linux-image-3.18.0-trunk + $$ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + + +[440][heading] +Custom kernels +[441][para] +You can build and include your own custom kernels, so long as they are integrated within the Debian package management system. The live-build system does not support kernels not built as #{.deb}# packages. +[442][para] +The proper and recommended way to deploy your own kernel packages is to follow the instructions in the #{kernel-handbook}#. Remember to modify the ABI and flavour suffixes appropriately, then include a complete build of the #{linux}# and matching #{linux-latest}# packages in your repository. +[443][para] +If you opt to build the kernel packages without the matching metapackages, you need to specify an appropriate #{--linux-packages}# stub as discussed in {Kernel flavour and version}#kernel-flavour-and-version. As we explain in {Installing modified or third-party packages}#installing-modified-or-third-party-packages, it is best if you include your custom kernel packages in your own repository, though the alternatives discussed in that section work as well. +[444][para] +It is beyond the scope of this document to give advice on how to customize your kernel. However, you must at least ensure your configuration satisfies these minimum requirements: +[445][para] +_* Use an initial ramdisk. +[446][para] +_* Include the union filesystem module (i.e. usually #{aufs}#). +[447][para] +_* Include any other filesystem modules required by your configuration (i.e. usually #{squashfs}#). +[448][heading] +Installing modified or third-party packages +[449][para] +While it is against the philosophy of a live system, it may sometimes be necessary to build a live system with modified versions of packages that are in the Debian repository. This may be to modify or support additional features, languages and branding, or even to remove elements of existing packages that are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietary functionality. +[450][para] +This section does not cover advice regarding building or maintaining modified packages. Joachim Breitner's 'How to fork privately' method from http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html may be of interest, however. The creation of bespoke packages is covered in the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ and elsewhere. +[451][para] +There are two ways of installing modified custom packages: +[452][para] +_* #{packages.chroot}# +[453][para] +_* Using a custom APT repository +[454][para] +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" customizations but has a number of drawbacks, while using a custom APT repository is more time-consuming to set up. +[455][heading] +Using #{packages.chroot}# to install custom packages +[456][para] +To install a custom package, simply copy it to the #{config/packages.chroot/}# directory. Packages that are inside this directory will be automatically installed into the live system during build - you do not need to specify them elsewhere. +[457][para] +Packages *{must}* be named in the prescribed way. One simple way to do this is to use #{dpkg-name}#. +[458][para] +Using #{packages.chroot}# for installation of custom packages has disadvantages: +[459][para] +_* It is not possible to use secure APT. +[460][para] +_* You must install all appropriate packages in the #{config/packages.chroot/}# directory. +[461][para] +_* It does not lend itself to storing live system configurations in revision control. +[462][heading] +Using an APT repository to install custom packages +[463][para] +Unlike using #{packages.chroot}#, when using a custom APT repository you must ensure that you specify the packages elsewhere. See {Choosing packages to install}#choosing-packages-to-install for details. +[464][para] +While it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified packages. +[465][heading] +Custom packages and APT +[466][para] +live-build uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package available in two different repositories with different version numbers, APT will elect to install the package with the higher version number. +[467][para] +Because of this, you may wish to increment the version number in your custom packages' #{debian/changelog}# files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see {APT pinning}#apt-pinning for more information. +[468][heading] +Configuring APT at build time +[469][para] +You can configure APT through a number of options applied only at build time. (APT configuration used in the running live system may be configured in the normal way for live system contents, that is, by including the appropriate configurations through #{config/includes.chroot/}#.) For a complete list, look for options starting with #{apt}# in the #{lb_config}# man page. +[470][heading] +Choosing apt or aptitude +[471][para] +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages at build time. Which utility is used is governed by the #{--apt}# argument to #{lb config}#. Choose the method implementing the preferred behaviour for package installation, the notable difference being how missing packages are handled. +[472][para] +_* #{apt}#: With this method, if a missing package is specified, the package installation will fail. This is the default setting. +[473][para] +_* #{aptitude}#: With this method, if a missing package is specified, the package installation will succeed. +[474][heading] +Using a proxy with APT +[475][para] +One commonly required APT configuration is to deal with building an image behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# or #{--apt-http-proxy}# options as needed, e.g. +[476][code] + + $$ lb config --apt-http-proxy http://proxy/ + + +[477][heading] +Tweaking APT to save space +[478][para] +You may find yourself needing to save some space on the image medium, in which case one or the other or both of the following options may be of interest. +[479][para] +If you don't want to include APT indices in the image, you can omit those with: +[480][code] + + $$ lb config --apt-indices false + + +[481][para] +This will not influence the entries in #{/etc/apt/sources.list}#, but merely whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is that APT needs those indices in order to operate in the live system, so before performing #{apt-cache search}# or #{apt-get install}#, for instance, the user must #{apt-get update}# first to create those indices. +[482][para] +If you find the installation of recommended packages bloats your image too much, provided you are prepared to deal with the consequences discussed below, you may disable that default option of APT with: +[483][code] + + $$ lb config --apt-recommends false + + +[484][para] +The most important consequence of turning off recommends is that #{live-boot}# and #{live-config}# themselves recommend some packages that provide important functionality used by most Live configurations, such as #{user-setup}# which #{live-config}# recommends and is used to create the live user. In all but the most exceptional circumstances you need to add back at least some of these recommends to your package lists or else your image will not work as expected, if at all. Look at the recommended packages for each of the #{live-*}# packages included in your build and if you are not certain you can omit them, add them back into your package lists. +[485][para] +The more general consequence is that if you don't install recommended packages for any given package, that is, "packages that would be found together with this one in all but unusual installations" (Debian Policy Manual, section 7.2), some packages that users of your Live system actually need may be omitted. Therefore, we suggest you review the difference turning off recommends makes to your packages list (see the #{binary.packages}# file generated by #{lb build}#) and re-include in your list any missing packages that you still want installed. Alternatively, if you find you only want a small number of recommended packages left out, leave recommends enabled and set a negative APT pin priority on selected packages to prevent them from being installed, as explained in {APT pinning}#apt-pinning. +[486][heading] +Passing options to apt or aptitude +[487][para] +If there is not a #{lb config}# option to alter APT's behaviour in the way you need, use #{--apt-options}# or #{--aptitude-options}# to pass any options through to your configured APT tool. See the man pages for #{apt}# and #{aptitude}# for details. Note that both options have default values that you will need to retain in addition to any overrides you may provide. So, for example, suppose you have included something from #{snapshot.debian.org}# for testing purposes and want to specify #{Acquire::Check-Valid-Until=false}# to make APT happy with the stale #{Release}# file, you would do so as per the following example, appending the new option after the default value #{--yes}#: +[488][code] + + $$ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + + +[489][para] +Please check the man pages to fully understand these options and when to use them. This is an example only and should not be construed as advice to configure your image this way. This option would not be appropriate for, say, a final release of a live image. +[490][para] +For more complicated APT configurations involving #{apt.conf}# options you might want to create a #{config/apt/apt.conf}# file instead. See also the other #{apt-*}# options for a few convenient shortcuts for frequently needed options. +[491][heading] +APT pinning +[492][para] +For background, please first read the #{apt_preferences(5)}# man page. APT pinning can be configured either for build time, or else for run time. For the former, create #{config/archives/*.pref}#, #{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the latter, create #{config/includes.chroot/etc/apt/preferences}#. +[493][para] +Let's say you are building a $${testing} live system but need all the live packages that end up in the binary image to be installed from sid at build time. You need to add sid to your APT sources and pin the live packages from it higher, but all other packages from it lower, than the default priority. Thus, only the packages you want are installed from sid at build time and all others are taken from the target system distribution, $${testing}. The following will accomplish this: +[494][code] + + $$ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $$ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + + +[495][para] +Negative pin priorities will prevent a package from being installed, as in the case where you do not want a package that is recommended by another package. Suppose you are building an LXDE image using #{task-lxde-desktop}# in #{config/package-lists/desktop.list.chroot}#, but don't want the user prompted to store wifi passwords in the keyring. This metapackage depends on /{lxde-core}/, which recommends /{gksu}/, which in turn recommends /{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ package. This can be done by adding the following stanza to #{config/apt/preferences}#: +[496][code] + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + + +[497][heading] +Customizing contents +[498][heading] +Customizing contents +[499][para] +This chapter discusses fine-tuning customization of the live system contents beyond merely choosing which packages to include. Includes allow you to add or replace arbitrary files in your live system image, hooks allow you to execute arbitrary commands at different stages of the build and at boot time, and preseeding allows you to configure packages when they are installed by supplying answers to debconf questions. +[500][heading] +Includes +[501][para] +While ideally a live system would include files entirely provided by unmodified packages, it is sometimes convenient to provide or modify some content by means of files. Using includes, it is possible to add (or replace) arbitrary files in your live system image. live-build provides two mechanisms for using them: +[502][para] +_* Chroot local includes: These allow you to add or replace files to the chroot/Live filesystem. Please see {Live/chroot local includes}#live-chroot-local-includes for more information. +[503][para] +_* Binary local includes: These allow you to add or replace files in the binary image. Please see {Binary local includes}#binary-local-includes for more information. +[504][para] +Please see {Terms}#terms for more information about the distinction between the "Live" and "binary" images. +[505][heading] +Live/chroot local includes +[506][para] +Chroot local includes can be used to add or replace files in the chroot/Live filesystem so that they may be used in the Live system. A typical use is to populate the skeleton user directory (#{/etc/skel}#) used by the Live system to create the live user's home directory. Another is to supply configuration files that can be simply added or replaced in the image without processing; see {Live/chroot local hooks}#live-chroot-local-hooks if processing is needed. +[507][para] +To include files, simply add them to your #{config/includes.chroot}# directory. This directory corresponds to the root directory #{/}# of the live system. For example, to add a file #{/var/www/index.html}# in the live system, use: +[508][code] + + $$ mkdir -p config/includes.chroot/var/www + $$ cp /path/to/my/index.html config/includes.chroot/var/www + + +[509][para] +Your configuration will then have the following layout: +[510][code] + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + + +[511][para] +Chroot local includes are installed after package installation so that files installed by packages are overwritten. +[512][heading] +Binary local includes +[513][para] +To include material such as documentation or videos on the medium filesystem so that it is accessible immediately upon insertion of the medium without booting the Live system, you can use binary local includes. This works in a similar fashion to chroot local includes. For example, suppose the files #{~/video_demo.*}# are demo videos of the live system described by and linked to by an HTML index page. Simply copy the material to #{config/includes.binary/}# as follows: +[514][code] + + $$ cp ~/video_demo.* config/includes.binary/ + + +[515][para] +These files will now appear in the root directory of the live medium. +[516][heading] +Hooks +[517][para] +Hooks allow commands to be performed in the chroot and binary stages of the build in order to customize the image. +[518][heading] +Live/chroot local hooks +[519][para] +To run commands in the chroot stage, create a hook script with a #{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run in the chroot after the rest of your chroot configuration has been applied, so remember to ensure your configuration includes all packages and files your hook needs in order to run. See the example chroot hook scripts for various common chroot customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. +[520][heading] +Boot-time hooks +[521][para] +To execute commands at boot time, you can supply live-config hooks as explained in the "Customization" section of its man page. Examine live-config's own hooks provided in #{/lib/live/config/}#, noting the sequence numbers. Then provide your own hook prefixed with an appropriate sequence number, either as a chroot local include in #{config/includes.chroot/lib/live/config/}#, or as a custom package as discussed in {Installing modified or third-party packages}#installing-modified-or-third-party-packages. +[522][heading] +Binary local hooks +[523][para] +To run commands in the binary stage, create a hook script with a #{.hook.binary}# suffix containing the commands in the #{config/hooks/}# directory. The hook will run after all other binary commands are run, but before binary_checksums, the very last binary command. The commands in your hook do not run in the chroot, so take care to not modify any files outside of the build tree, or you may damage your build system! See the example binary hook scripts for various common binary customization tasks provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or symlink to use them in your own configuration. +[524][heading] +Preseeding Debconf questions +[525][para] +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf preseed files and are installed by live-build using #{debconf-set-selections}# during the corresponding stage. +[526][para] +For more information about debconf, please see #{debconf(7)}# in the /{debconf}/ package. +[527][heading] +Customizing run time behaviours +[528][heading] +Customizing run time behaviours +[529][para] +All configuration that is done during run time is done by live-config. Here are some of the most common options of live-config that users are interested in. A full list of all possibilities can be found in the man page of live-config. +[530][heading] +Customizing the live user +[531][para] +One important consideration is that the live user is created by live-boot at boot time, not by live-build at build time. This not only influences where materials relating to the live user are introduced in your build, as discussed in {Live/chroot local includes}#live-chroot-local-includes, but also any groups and permissions associated with the live user. +[532][para] +You can specify additional groups that the live user will belong to by using any of the possibilities to configure live-config. For example, to add the live user to the #{fuse}# group, you can either add the following file in #{config/includes.chroot/etc/live/config/user-setup.conf}#: +[533][code] + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + + +[534][para] +or use #{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# as a boot parameter. +[535][para] +It is also possible to change the default username "user" and the default password "live". If you want to do that for any reason, you can easily achieve it as follows: +[536][para] +To change the default username you can simply specify it in your config: +[537][code] + + $$ lb config --bootappend-live "boot=live components username=live-user" + + +[538][para] +One possible way of changing the default password is by means of a hook as described in {Boot-time hooks}#boot-time-hooks. In order to do that you can use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, prefix it accordingly (e.g. 2000-passwd) and add it to #{config/includes.chroot/lib/live/config/}# +[539][heading] +Customizing locale and language +[540][para] +When the live system boots, language is involved in two steps: +[541][para] +_* the locale generation +[542][para] +_* setting the keyboard configuration +[543][para] +The default locale when building a Live system is #{locales=en_US.UTF-8}#. To define the locale that should be generated, use the #{locales}# parameter in the #{--bootappend-live}# option of #{lb config}#, e.g. +[544][code] + + $$ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + + +[545][para] +Multiple locales may be specified as a comma-delimited list. +[546][para] +This parameter, as well as the keyboard configuration parameters indicated below, can also be used at the kernel command line. You can specify a locale by #{language_country}# (in which case the default encoding is used) or the full #{language_country.encoding}# word. A list of supported locales and the encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. +[547][para] +Both the console and X keyboard configuration are performed by #{live-config}# using the #{console-setup}# package. To configure them, use the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and #{keyboard-model}# boot parameters via the #{--bootappend-live}# option. Valid options for these can be found in #{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a given language, try searching for the English name of the language and/or the country where the language is spoken, e.g: +[548][code] + +$$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + + +[549][para] +Note that each variant lists the layout to which it applies in the description. +[550][para] +Often, only the layout needs to be configured. For example, to get the locale files for German and Swiss German keyboard layout in X use: +[551][code] + + $$ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + + +[552][para] +However, for very specific use cases, you may wish to include other parameters. For example, to set up a French system with a French-Dvorak layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: +[553][code] + + $$ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + + +[554][para] +Multiple values may be specified as comma-delimited lists for each of the #{keyboard-*}# options, with the exception of #{keyboard-model}#, which accepts only one value. Please see the #{keyboard(5)}# man page for details and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and #{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are given, they will be matched one-to-one with #{keyboard-layouts}# values (see #{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to define two layouts, the default being US QWERTY and the other being US Dvorak, use: +[555][code] + + $$ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + + +[556][heading] +Persistence +[557][para] +A live cd paradigm is a pre-installed system which runs from read-only media, like a cdrom, where writes and modifications do not survive reboots of the host hardware which runs it. +[558][para] +A live system is a generalization of this paradigm and thus supports other media in addition to CDs; but still, in its default behaviour, it should be considered read-only and all the run-time evolutions of the system are lost at shutdown. +[559][para] +'Persistence' is a common name for different kinds of solutions for saving across reboots some, or all, of this run-time evolution of the system. To understand how it works it would be handy to know that even if the system is booted and run from read-only media, modifications to the files and directories are written on writable media, typically a ram disk (tmpfs) and ram disks' data do not survive reboots. +[560][para] +The data stored on this ramdisk should be saved on a writable persistent medium like local storage media, a network share or even a session of a multisession (re)writable CD/DVD. All these media are supported in live systems in different ways, and all but the last one require a special boot parameter to be specified at boot time: #{persistence}#. +[561][para] +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not set), local storage media (e.g. hard disks, USB drives) will be probed for persistence volumes during boot. It is possible to restrict which types of persistence volumes to use by specifying certain boot parameters described in the live-boot(7) man page. A persistence volume is any of the following: +[562][para] +_* a partition, identified by its GPT name. +[563][para] +_* a filesystem, identified by its filesystem label. +[564][para] +_* an image file located on the root of any readable filesystem (even an NTFS partition of a foreign OS), identified by its filename. +[565][para] +The volume label for overlays must be #{persistence}# but it will be ignored unless it contains in its root a file named #{persistence.conf}# which is used to fully customize the volume's persistence, this is to say, specifying the directories that you want to save in your persistence volume after a reboot. See {The persistence.conf file}#persistence-conf for more details. +[566][para] +Here are some examples of how to prepare a volume to be used for persistence. It can be, for instance, an ext4 partition on a hard disk or on a usb key created with, e.g.: +[567][code] + + # mkfs.ext4 -L persistence /dev/sdb1 + + +[568][para] +See also {Using the space left on a USB stick}#using-usb-extra-space. +[569][para] +If you already have a partition on your device, you could just change the label with one of the following: +[570][code] + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + + +[571][para] +Here's an example of how to create an ext4-based image file to be used for persistence: +[572][code] + + $$ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $$ /sbin/mkfs.ext4 -F persistence + + +[573][para] +Once the image file is created, as an example, to make #{/usr}# persistent but only saving the changes you make to that directory and not all the contents of #{/usr}#, you can use the "union" option. If the image file is located in your home directory, copy it to the root of your hard drive's filesystem and mount it in #{/mnt}# as follows: +[574][code] + + # cp persistence / + # mount -t ext4 /persistence /mnt + + +[575][para] +Then, create the #{persistence.conf}# file adding content and unmount the image file. +[576][code] + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + + +[577][para] +Now, reboot into your live medium with the boot parameter "persistence". +[578][heading] +The persistence.conf file +[579][para] +A volume with the label #{persistence}# must be configured by means of the #{persistence.conf}# file to make arbitrary directories persistent. That file, located on the volume's filesystem root, controls which directories it makes persistent, and in which way. +[580][para] +How custom overlay mounts are configured is described in full detail in the persistence.conf(5) man page, but a simple example should be sufficient for most uses. Let's say we want to make our home directory and APT cache persistent in an ext4 filesystem on the /dev/sdb1 partition: +[581][code] + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + + +[582][para] +Then we reboot. During the first boot the contents of #{/home}# and #{/var/cache/apt}# will be copied into the persistence volume, and from then on all changes to these directories will live in the persistence volume. Please note that any paths listed in the #{persistence.conf}# file cannot contain white spaces or the special #{.}# and #{..}# path components. Also, neither #{/lib}#, #{/lib/live}# (or any of their sub-directories) nor #{/}# can be made persistent using custom mounts. As a workaround for this limitation you can add #{/ union}# to your #{persistence.conf}# file to achieve full persistence. +[583][heading] +Using more than one persistence store +[584][para] +There are different methods of using multiple persistence store for different use cases. For instance, using several volumes at the same time or selecting only one, among various, for very specific purposes. +[585][para] +Several different custom overlay volumes (with their own #{persistence.conf}# files) can be used at the same time, but if several volumes make the same directory persistent, only one of them will be used. If any two mounts are "nested" (i.e. one is a sub-directory of the other) the parent will be mounted before the child so no mount will be hidden by the other. Nested custom mounts are problematic if they are listed in the same #{persistence.conf}# file. See the persistence.conf(5) man page for how to handle that case if you really need it (hint: you usually don't). +[586][para] +One possible use case: If you wish to store the user data i.e. #{/home}# and the superuser data i.e. #{/root}# in different partitions, create two partitions with the #{persistence}# label and add a #{persistence.conf}# file in each one like this, #{# echo "/home" > persistence.conf}# for the first partition that will save the user's files and #{# echo "/root" > persistence.conf}# for the second partition which will store the superuser's files. Finally, use the #{persistence}# boot parameter. +[587][para] +If a user would need multiple persistence store of the same type for different locations or testing, such as #{private}# and #{work}#, the boot parameter #{persistence-label}# used in conjunction with the boot parameter #{persistence}# will allow for multiple but unique persistence media. An example would be if a user wanted to use a persistence partition labeled #{private}# for personal data like browser bookmarks or other types, they would use the boot parameters: #{persistence}# #{persistence-label=private}#. And to store work related data, like documents, research projects or other types, they would use the boot parameters: #{persistence}# #{persistence-label=work}#. +[588][para] +It is important to remember that each of these volumes, #{private}# and #{work}#, also needs a #{persistence.conf}# file in its root. The live-boot man page contains more information about how to use these labels with legacy names. +[589][heading] +Using persistence with encryption +[590][para] +Using the persistence feature means that some sensible data might get exposed to risk. Especially if the persistent data is stored on a portable device such as a usb stick or an external hard drive. That is when encryption comes in handy. Even if the entire procedure might seem complicated because of the number of steps to be taken, it is really easy to handle encrypted partitions with live-boot. In order to use *{luks}*, which is the supported encryption type, you need to install /{cryptsetup}/ both on the machine you are creating the encrypted partition with and also in the live system you are going to use the encrypted persistent partition with. +[591][para] +To install /{cryptsetup}/ on your machine: +[592][code] + + # apt-get install cryptsetup + + +[593][para] +To install /{cryptsetup}/ in your live system, add it to your package-lists: +[594][code] + + $$ lb config + $$ echo "cryptsetup" > config/package-lists/encryption.list.chroot + + +[595][para] +Once you have your live system with /{cryptsetup}/, you basically only need to create a new partition, encrypt it and boot with the #{persistence}# and #{persistence-encryption=luks}# parameters. We could have already anticipated this step and added the boot parameters following the usual procedure: +[596][code] + + $$ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + + +[597][para] +Let's go into the details for all of those who are not familiar with encryption. In the following example we are going to use a partition on a usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need to determine which partition is the one you are going to use in your specific case. +[598][para] +The first step is plugging in your usb stick and determine which device it is. The recommended method of listing devices in live-manual is using #{ls -l /dev/disk/by-id}#. After that, create a new partition and then, encrypt it with a passphrase as follows: +[599][code] + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + + +[600][para] +Then open the luks partition in the virtual device mapper. Use any name you like. We use *{live}* here as an example: +[601][code] + + # cryptsetup luksOpen /dev/sdc2 live + + +[602][para] +The next step is filling the device with zeros before creating the filesystem: +[603][code] + + # dd if=/dev/zero of=/dev/mapper/live + + +[604][para] +Now, we are ready to create the filesystem. Notice that we are adding the label #{persistence}# so that the device is mounted as persistence store at boot time. +[605][code] + + # mkfs.ext4 -L persistence /dev/mapper/live + + +[606][para] +To continue with our setup, we need to mount the device, for example in #{/mnt}#. +[607][code] + + # mount /dev/mapper/live /mnt + + +[608][para] +And create the #{persistence.conf}# file in the root of the partition. This is, as explained before, strictly necessary. See {The persistence.conf file}#persistence-conf. +[609][code] + + # echo "/ union" > /mnt/persistence.conf + + +[610][para] +Then unmount the mount point: +[611][code] + + # umount /mnt + + +[612][para] +And optionally, although it might be a good way of securing the data we have just added to the partition, we can close the device: +[613][code] + + # cryptsetup luksClose live + + +[614][para] +Let's summarize the process. So far, we have created an encryption capable live system, which can be copied to a usb stick as explained in {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also created an encrypted partition, which can be located in the same usb stick to carry it around and we have configured the encrypted partition to be used as persistence store. So now, we only need to boot the live system. At boot time, live-boot will prompt us for the passphrase and will mount the encrypted partition to be used for persistence. +[615][heading] +Customizing the binary image +[616][heading] +Customizing the binary image +[617][heading] +Bootloaders +[618][para] +live-build uses /{syslinux}/ and some of its derivatives (depending on the image type) as bootloaders by default. They can be easily customized to suit your needs. +[619][para] +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# into #{config/bootloaders}# and edit the files in there. If you do not want to bother modifying all supported bootloader configurations, only providing a local customized copy of one of the bootloaders, e.g. *{isolinux}* in #{config/bootloaders/isolinux}# is enough too, depending on your use case. +[620][para] +When modifying one of the default themes, if you want to use a personalized background image that will be displayed together with the boot menu, add a splash.png picture of 640x480 pixels. Then, remove the splash.svg file. +[621][para] +There are many possibilities when it comes to making changes. For instance, syslinux derivatives are configured by default with a timeout of 0 (zero) which means that they will pause indefinitely at their splash screen until you press a key. +[622][para] +To modify the boot timeout of a default #{iso-hybrid}# image just edit a default *{isolinux.cfg}* file specifying the timeout in units of 1/10 seconds. A modified *{isolinux.cfg}* to boot after five seconds would be similar to this: +[623][code] + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + + +[624][heading] +ISO metadata +[625][para] +When creating an ISO9660 binary image, you can use the following options to add various textual metadata for your image. This can help you easily identify the version or configuration of an image without booting it. +[626][para] +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the application that will be on the image. The maximum length for this field is 128 characters. +[627][para] +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the preparer of the image, usually with some contact details. The default for this option is the live-build version you are using, which may help with debugging later. The maximum length for this field is 128 characters. +[628][para] +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters. +[629][para] +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of the image. This is used as a user-visible label on some platforms such as Windows and Apple Mac OS. The maximum length for this field is 32 characters. +[630][heading] +Customizing Debian Installer +[631][heading] +Customizing Debian Installer +[632][para] +Live system images can be integrated with Debian Installer. There are a number of different types of installation, varying in what is included and how the installer operates. +[633][para] +Please note the careful use of capital letters when referring to the "Debian Installer" in this section - when used like this we refer explicitly to the official installer for the Debian system, not anything else. It is often seen abbreviated to "d-i". +[634][heading] +Types of Debian Installer +[635][para] +The three main types of installer are: +[636][para] +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". +[637][para] +On such images, Debian is installed by fetching and installing .deb packages using /{debootstrap}/, from local media or some network-based network, resulting in a default Debian system being installed to the hard disk. +[638][para] +This whole process can be preseeded and customized in a number of ways; see the relevant pages in the Debian Installer manual for more information. Once you have a working preseeding file, live-build can automatically put it in the image and enable it for you. +[639][para] +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. +[640][para] +Installation will proceed in an identical fashion to the "normal" installation described above, but at the actual package installation stage, instead of using /{debootstrap}/ to fetch and install packages, the live filesystem image is copied to the target. This is achieved with a special udeb called live-installer. +[641][para] +After this stage, the Debian Installer continues as normal, installing and configuring items such as bootloaders and local users, etc. +[642][para] +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. +[643][para] +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. +[644][para] +Note that by default, live-build does not include Debian Installer images in the images, it needs to be specifically enabled with #{lb config}#. Also, please note that for the "Desktop" installer to work, the kernel of the live system must match the kernel #{d-i}# uses for the specified architecture. For example: +[645][code] + + $$ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $$ echo debian-installer-launcher >> config/package-lists/my.list.chroot + + +[646][heading] +Customizing Debian Installer by preseeding +[647][para] +As described in the Debian Installer Manual, Appendix B at https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a way to set answers to questions asked during the installation process, without having to manually enter the answers while the installation is running. This makes it possible to fully automate most types of installation and even offers some features not available during normal installations." This kind of customization is best accomplished with live-build by placing the configuration in a #{preseed.cfg}# file included in #{config/includes.installer/}#. For example, to preseed setting the locale to #{en_US}#: +[648][code] + + $$ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + + +[649][heading] +Customizing Debian Installer content +[650][para] +For experimental or debugging purposes, you might want to include locally built #{d-i}# component udeb packages. Place these in #{config/packages.binary/}# to include them in the image. Additional or replacement files and directories may be included in the installer initrd as well, in a similar fashion to {Live/chroot local includes}#live-chroot-local-includes, by placing the material in #{config/includes.installer/}#. +[651][heading] +Project +[652][heading] +Contributing to the project +[653][heading] +Contributing to the project +[654][para] +When submitting a contribution, please clearly identify its copyright holder and include any applicable licensing statement. Note that to be accepted, the contribution must be licensed under the same license as the rest of the documents, namely, GPL version 3 or later. +[655][para] +Contributions to the project, such as translations and patches, are greatly welcome. Anyone can directly commit to the repositories, however, we ask you to send bigger changes to the mailing list to discuss them first. See the section {Contact}#contact for more information. +[656][para] +The $${project} uses Git as version control system and source code management. As explained in {Git repositories}#git-repositories there are two main development branches: *{debian}* and *{debian-next}*. Everybody can commit to the debian-next branches of the live-boot, live-build, live-config, live-images, live-manual and live-tools repositories. +[657][para] +However, there are certain restrictions. The server will reject: +[658][para] +_* Non fast-forward pushes. +[659][para] +_* Merge commits. +[660][para] +_* Adding or removing tags or branches. +[661][para] +Even though all commits might be revised, we ask you to use your common sense and make good commits with good commit messages. +[662][para] +_* Write commit messages that consist of complete, meaningful sentences in English, starting with a capital letter and ending with a full stop. Usually, these will start with the form "Fixing/Adding/Removing/Correcting/Translating/...". +[663][para] +_* Write good commit messages. The first line must be an accurate summary of the contents of the commit which will be included in the changelog. If you need to make some further explanations, write them below leaving a blank line after the first one and then another blank line after each paragraph. Lines of paragraphs should not exceed 80 characters in length. +[664][para] +_* Commit atomically, this is to say, do not mix unrelated things in the same commit. Make one different commit for each change you make. +[665][heading] +Making changes +[666][para] +In order to push to the repositories, you must follow the following procedure. Here we use live-manual as an example so replace it with the name of the repository you want to work with. For detailed information on how to edit live-manual see {Contributing to this document}#how-to-contribute. +[667][para] +_* Fetch the public commit key: +[668][code] + + $$ mkdir -p ~/.ssh/keys + $$ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $$ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $$ chmod 0600 ~/.ssh/keys/git@live-systems.org* + + +[669][para] +_* Add the following section to your openssh-client config: +[670][code] + + $$ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + + +[671][para] +_* Check out a clone of live-manual through ssh: +[672][code] + + $$ git clone git@live-systems.org:/live-manual.git + $$ cd live-manual && git checkout debian-next + + +[673][para] +_* Make sure you have Git author and email set: +[674][code] + + $$ git config user.name "John Doe" + $$ git config user.email john@example.org + + +[675][para] +*{Important:}* Remember that you should commit any changes on the *{debian-next}* branch. +[676][para] +_* Make your changes. In this example you would first write a new section dealing with applying patches and then prepare to commit adding the files and writing your commit message like this: +[677][code] + + $$ git commit -a -m "Adding a section on applying patches." + + +[678][para] +_* Push the commit to the server: +[679][code] + + $$ git push + + +[680][heading] +Reporting bugs +[681][heading] +Reporting bugs +[682][para] +Live systems are far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug. It is better to fill a report twice than never. However, this chapter includes recommendations on how to file good bug reports. +[683][para] +For the impatient: +[684][para] +_* Always check first the image status updates on our homepage at http://live-systems.org/ for known issues. +[685][para] +_* Before submitting a bug report always try to reproduce the bug with the *{most recent versions}* of the branch of live-build, live-boot, live-config and live-tools that you're using (like the newest 4.x version of live-build if you're using live-build 4). +[686][para] +_* Try to give *{as specific information as possible}* about the bug. This includes (at least) the version of live-build, live-boot, live-config, and live-tools used and the distribution of the live system you are building. +[687][heading] +Known issues +[688][para] +Since Debian *{testing}* and Debian *{unstable}* distributions are moving targets, when you specify either of them as the target system distribution, a successful build may not always be possible. +[689][para] +If this causes too much difficulty for you, do not build a system based on *{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always defaults to the *{stable}* release. +[690][para] +Currently known issues are listed under the section 'status' on our homepage at http://live-systems.org/. +[691][para] +It is out of the scope of this manual to train you to correctly identify and fix problems in packages of the development distributions, however, there are two things you can always try: If a build fails when the target distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work either, revert to *{testing}* and pin the newer version of the failing package from *{unstable}* (see {APT pinning}#apt-pinning for details). +[692][heading] +Rebuild from scratch +[693][para] +To ensure that a particular bug is not caused by an uncleanly built system, please always rebuild the whole live system from scratch to see if the bug is reproducible. +[694][heading] +Use up-to-date packages +[695][para] +Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. Make sure your build system is up-to-date and any packages included in your image are up-to-date as well. +[696][heading] +Collect information +[697][para] +Please provide enough information with your report. Include, at least, the exact version of live-build where the bug is encountered and the steps to reproduce it. Please use your common sense and provide any other relevant information if you think that it might help in solving the problem. +[698][para] +To make the most out of your bug report, we require at least the following information: +[699][para] +_* Architecture of the host system +[700][para] +_* Distribution of the host system +[701][para] +_* Version of live-build on the host system +[702][para] +_* Version of /{debootstrap}/ on the host system +[703][para] +_* Architecture of the live system +[704][para] +_* Distribution of the live system +[705][para] +_* Version of live-boot on the live system +[706][para] +_* Version of live-config on the live system +[707][para] +_* Version of live-tools on the live system +[708][para] +You can generate a log of the build process by using the #{tee}# command. We recommend doing this automatically with an #{auto/build}# script (see {Managing a configuration}#managing-a-configuration for details). +[709][code] + + # lb build 2>&1 | tee build.log + + +[710][para] +At boot time, live-boot and live-config store their logfiles in #{/var/log/live/}#. Check them for error messages. +[711][para] +Additionally, to rule out other errors, it is always a good idea to tar up your #{config/}# directory and upload it somewhere (do *{not}* send it as an attachment to the mailing list), so that we can try to reproduce the errors you encountered. If this is difficult (e.g. due to size) you can use the output of #{lb config --dump}# which produces a summary of your config tree (i.e. lists files in subdirectories of #{config/}# but does not include them). +[712][para] +Remember to send in any logs that were produced with English locale settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or #{LC_ALL=en_US}#. +[713][heading] +Isolate the failing case if possible +[714][para] +If possible, isolate the failing case to the smallest possible change that breaks. It is not always easy to do this so if you cannot manage it for your report, do not worry. However, if you plan your development cycle well, using small enough change sets per iteration, you may be able to isolate the problem by constructing a simpler 'base' configuration that closely matches your actual configuration plus just the broken change set added to it. If you have a hard time sorting out which of your changes broke, it may be that you are including too much in each change set and should develop in smaller increments. +[715][heading] +Use the correct package to report the bug against +[716][para] +If you do not know what component is responsible for the bug or if the bug is a general bug concerning live systems, you can fill a bug against the debian-live pseudo-package. +[717][para] +However, we would appreciate it if you try to narrow it down according to where the bug appears. +[718][heading] +At build time while bootstrapping +[719][para] +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to the bootstrapping tool itself. +[720][para] +In both cases, this is not a bug in the live system, but rather in Debian itself and probably we cannot fix it directly. Please report such a bug against the bootstrapping tool or the failing package. +[721][heading] +At build time while installing packages +[722][para] +live-build installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system. +[723][para] +If this is the case, this is not a bug in the live system, but rather in Debian - please report it against the failing package. Running /{debootstrap}/ separately from the Live system build or running #{lb bootstrap --debug}# will give you more information. +[724][para] +Also, if you are using a local mirror and/or any sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror. +[725][heading] +At boot time +[726][para] +If your image does not boot, please report it to the mailing list together with the information requested in {Collect information}#collect-information. Do not forget to mention, how/when the image failed exactly, whether using virtualization or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful. +[727][heading] +At run time +[728][para] +If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in the live system. However: +[729][heading] +Do the research +[730][para] +Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem. There is always a chance that it has been discussed elsewhere and a possible solution, patch, or workaround has been proposed. +[731][para] +You should pay particular attention to the live systems mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report. +[732][para] +In addition, you should check the current bug lists for live-build, live-boot, live-config and live-tools to see whether something similar has already been reported. +[733][heading] +Where to report bugs +[734][para] +The $${project} keeps track of all bugs in the Bug Tracking System (BTS). For information on how to use the system, please see https://bugs.debian.org/. You can also submit the bugs by using the #{reportbug}# command from the package with the same name. +[735][para] +In general, you should report build time errors against the live-build package, boot time errors against live-boot, and run time errors against live-config. If you are unsure of which package is appropriate or need more help before submitting a bug report, please report it against the debian-live pseudo-package. We will then take care about it and reassign it where appropriate. +[736][para] +Please note that bugs found in distributions derived from Debian (such as Ubuntu and others) should *{not}* be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages. +[737][heading] +Coding Style +[738][heading] +Coding Style +[739][para] +This chapter documents the coding style used in live systems. +[740][heading] +Compatibility +[741][para] +_* Don't use syntax or semantics that are unique to the Bash shell. For example, the use of array constructs. +[742][para] +_* Only use the POSIX subset - for example, use $$(foo) over `foo`. +[743][para] +_* You can check your scripts with 'sh -n' and 'checkbashisms'. +[744][para] +_* Make sure all shell code runs with 'set -e'. +[745][heading] +Indenting +[746][para] +_* Always use tabs over spaces. +[747][heading] +Wrapping +[748][para] +_* Generally, lines are 80 chars at maximum. +[749][para] +_* Use the "Linux style" of line breaks: +[750][para] +Bad: +[751][code] + + if foo; then + bar + fi + + +[752][para] +Good: +[753][code] + + if foo + then + bar + fi + + +[754][para] +_* The same holds for functions: +[755][para] +Bad: +[756][code] + + Foo () { + bar + } + + +[757][para] +Good: +[758][code] + + Foo () + { + bar + } + + +[759][heading] +Variables +[760][para] +_* Variables are always in capital letters. +[761][para] +_* Variables used in live-build always start with #{LB_}# prefix. +[762][para] +_* Internal temporary variables in live-build should start with the #{\_LB_}# prefix. +[763][para] +_* Local variables start with live-build #{\_\_LB_}# prefix. +[764][para] +_* Variables in connection to a boot parameter in live-config start with #{LIVE_}#. +[765][para] +_* All other variables in live-config start with #{_}# prefix. +[766][para] +_* Use braces around variables; e.g. write #{$${FOO}}# instead of #{$$FOO}#. +[767][para] +_* Always protect variables with quotes to respect potential whitespaces: write #{"$${FOO}"}# not #{$${FOO}}#. +[768][para] +_* For consistency reasons, always use quotes when assigning values to variables: +[769][para] +Bad: +[770][code] + + FOO=bar + + +[771][para] +Good: +[772][code] + + FOO="bar" + + +[773][para] +_* If multiple variables are used, quote the full expression: +[774][para] +Bad: +[775][code] + + if [ -f "$${FOO}"/foo/"$${BAR}"/bar ] + then + foobar + fi + + +[776][para] +Good: +[777][code] + + if [ -f "$${FOO}/foo/$${BAR}/bar" ] + then + foobar + fi + + +[778][heading] +Miscellaneous +[779][para] +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, e.g. "#{sed -e 's|foo|bar|'}#" (without ""). +[780][para] +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" "#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test -x /bin/foo; ...}#". +[781][para] +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and faster in execution. +[782][para] +_* Use capitalized names for functions to limit messing with the users environment. +[783][heading] +Procedures +[784][heading] +Procedures +[785][para] +This chapter documents the procedures within the $${project} for various tasks that need cooperation with other teams in Debian. +[786][heading] +Major Releases +[787][para] +Releasing a new stable major version of Debian includes a lot of different teams working together to make it happen. At some point, the Live team comes in and builds live system images. The requirements to do this are: +[788][para] +_* A mirror containing the released versions for the debian and debian-security archives which the debian-live buildd can access. +[789][para] +_* The names of the image need to be known (e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). +[790][para] +_* The data from debian-cd needs to be synced (udeb exclude lists). +[791][para] +_* Images are built and mirrored on cdimage.debian.org. +[792][heading] +Point Releases +[793][para] +_* Again, we need updated mirrors of debian and debian-security. +[794][para] +_* Images are built and mirrored on cdimage.debian.org. +[795][para] +_* Send announcement mail. +[796][heading] +Last Point Release of a Debian Release +[797][para] +Remember to adjust both chroot and binary mirrors when building the last set ofimages for a Debian release after it has been moved away from ftp.debian.org toarchive.debian.org. That way, old prebuilt live images are still useful withoutuser modifications. +[798][heading] +Point release announcement template +[799][para] +An announcement mail for point releases can be generated using the template below and the following command: +[800][code] + + $$ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + + +[801][para] +Please check the mail carefully before sending and pass it to others for proof-reading. +[802][code] + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + + +[803][heading] +Git repositories +[804][heading] +Git repositories +[805][para] +The list of all the available repositories of the $${project} can be found at http://live-systems.org/gitweb/. The project's git URLs have the form: #{protocol://live-systems.org/git/repository}#. Thus, in order to clone live-manual read-only, launch: +[806][code] + + $$ git clone git://live-systems.org/git/live-manual.git + + +[807][para] +Or, +[808][code] + + $$ git clone https://live-systems.org/git/live-manual.git + + +[809][para] +Or, +[810][code] + + $$ git clone http://live-systems.org/git/live-manual.git + + +[811][para] +The cloning addresses with write permission have the form: #{git@live-systems.org:/repository}#. +[812][para] +So, again, to clone live-manual over ssh you must type: +[813][code] + + $$ git clone git@live-systems.org:live-manual.git + + +[814][para] +The git tree is made up of several different branches. The *{debian}* and the *{debian-next}* branches are particularly noteworthy because they contain the actual work that will eventually be included in each new release. +[815][para] +After cloning any of the existing repositories, you will be on the *{debian}* branch. This is appropriate to take a look at the state of the project's latest release but before starting work it is crucial to switch to the *{debian-next}* branch. To do so: +[816][code] + + $$ git checkout debian-next + + +[817][para] +The *{debian-next}* branch, which is not always fast-forward, is where all the changes are committed first before being merged into the *{debian}* branch. To make an analogy, it is like a testing ground. If you are working on this branch and need to pull, you will have to do a #{git pull --rebase}# so that your local modifications are staged while pulling from the server and then your changes will be put on top of it all. +[818][heading] +Handling multiple repositories +[819][para] +If you intend to clone several of the live systems repositories and want to switch to the *{debian-next}* branch right away to check the latest code, write a patch or contribute with a translation you ought to know that the git server provides a #{mrconfig}# file to ease the handling of multiple repositories. In order to use it you need to install the /{mr}/ package and after that, launch: +[820][code] + + $$ mr bootstrap http://live-systems.org/other/mr/mrconfig + + +[821][para] +This command will automatically clone and checkout to the *{debian-next}* branch the development repositories of the Debian packages produced by the project. These include, among others, the live-images repository, which contains the configurations used for the prebuilt images that the project publishes for general use. For more information on how to use this repository, see {Clone a configuration published via Git}#clone-configuration-via-git +[822][heading] +Examples +[823][heading] +Examples +[824][heading] +Examples +[825][para] +This chapter covers example builds for specific use cases with live systems. If you are new to building your own live system images, we recommend you first look at the three tutorials in sequence, as each one teaches new techniques that will help you use and understand the remaining examples. +[826][heading] +Using the examples +[827][para] +To use these examples you need a system to build them on that meets the requirements listed in {Requirements}#requirements and has live-build installed as described in {Installing live-build}#installing-live-build. +[828][para] +Note that, for the sake of brevity, in these examples we do not specify a local mirror to use for the build. You can speed up downloads considerably if you use a local mirror. You may specify the options when you use #{lb config}#, as described in {Distribution mirrors used at build time}#distribution-mirrors-build-time, or for more convenience, set the default for your build system in #{/etc/live/build.conf}#. Simply create this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your preferred mirror. All other mirrors used in the build will be defaulted from these values. For example: +[829][code] + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + + +[830][heading] +Tutorial 1: A default image +[831][para] +*{Use case:}* Create a simple first image, learning the basics of live-build. +[832][para] +In this tutorial, we will build a default ISO hybrid live system image containing only base packages (no Xorg) and some live system support packages, as a first exercise in using live-build. +[833][para] +You can't get much simpler than this: +[834][code] + + $$ mkdir tutorial1 ; cd tutorial1 ; lb config + + +[835][para] +Examine the contents of the #{config/}# directory if you wish. You will see stored here a skeletal configuration, ready to customize or, in this case, use immediately to build a default image. +[836][para] +Now, as superuser, build the image, saving a log as you build with #{tee}#. +[837][code] + + # lb build 2>&1 | tee build.log + + +[838][para] +Assuming all goes well, after a while, the current directory will contain #{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly in a virtual machine as described in {Testing an ISO image with Qemu}#testing-iso-with-qemu and {Testing an ISO image with VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media or a USB flash device as described in {Burning an ISO image to a physical medium}#burning-iso-image and {Copying an ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb, respectively. +[839][heading] +Tutorial 2: A web browser utility +[840][para] +*{Use case:}* Create a web browser utility image, learning how to apply customizations. +[841][para] +In this tutorial, we will create an image suitable for use as a web browser utility, serving as an introduction to customizing live system images. +[842][code] + + $$ mkdir tutorial2 + $$ cd tutorial2 + $$ lb config + $$ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + + +[843][para] +Our choice of LXDE for this example reflects our desire to provide a minimal desktop environment, since the focus of the image is the single use we have in mind, the web browser. We could go even further and provide a default configuration for the web browser in #{config/includes.chroot/etc/iceweasel/profile/}#, or additional support packages for viewing various kinds of web content, but we leave this as an exercise for the reader. +[844][para] +Build the image, again as superuser, keeping a log as in {Tutorial 1}#tutorial-1: +[845][code] + + # lb build 2>&1 | tee build.log + + +[846][para] +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. +[847][heading] +Tutorial 3: A personalized image +[848][para] +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. +[849][para] +Since we will be changing our personalized image over a number of revisions, and we want to track those changes, trying things experimentally and possibly reverting them if things don't work out, we will keep our configuration in the popular #{git}# version control system. We will also use the best practice of autoconfiguration via #{auto}# scripts as described in {Managing a configuration}#managing-a-configuration. +[850][heading] +First revision +[851][code] + + $$ mkdir -p tutorial3/auto + $$ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $$ cd tutorial3 + + +[852][para] +Edit #{auto/config}# to read as follows: +[853][code] + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "$${@}" + + +[854][para] +Perform #{lb config}# to generate the config tree, using the #{auto/config}# script you just created: +[855][code] + + $$ lb config + + +[856][para] +Now populate your local package list: +[857][code] + + $$ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + + +[858][para] +First, #{--architectures i386}# ensures that on our #{amd64}# build system, we build a 32-bit version suitable for use on most machines. Second, we use #{--linux-flavours 686-pae}# because we don't anticipate using this image on much older systems. Third, we have chosen the /{lxde}/ task metapackage to give us a minimal desktop. And finally, we have added two initial favourite packages: /{iceweasel}/ and /{xchat}/. +[859][para] +Now, build the image: +[860][code] + + # lb build + + +[861][para] +Note that unlike in the first two tutorials, we no longer have to type #{2>&1 | tee build.log}# as that is now included in #{auto/build}#. +[862][para] +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are satisfied it works, it's time to initialize our #{git}# repository, adding only the auto scripts we just created, and then make the first commit: +[863][code] + + $$ git init + $$ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $$ git add . + $$ git commit -m "Initial import." + + +[864][heading] +Second revision +[865][para] +In this revision, we're going to clean up from the first build, add the /{vlc}/ package to our configuration, rebuild, test and commit. +[866][para] +The #{lb clean}# command will clean up all generated files from the previous build except for the cache, which saves having to re-download packages. This ensures that the subsequent #{lb build}# will re-run all stages to regenerate the files from our new configuration. +[867][code] + + # lb clean + + +[868][para] +Now append the /{vlc}/ package to our local package list in #{config/package-lists/my.list.chroot}#: +[869][code] + + $$ echo vlc >> config/package-lists/my.list.chroot + + +[870][para] +Build again: +[871][code] + +# lb build + + +[872][para] +Test, and when you're satisfied, commit the next revision: +[873][code] + + $$ git commit -a -m "Adding vlc media player." + + +[874][para] +Of course, more complicated changes to the configuration are possible, perhaps adding files in subdirectories of #{config/}#. When you commit new revisions, just take care not to hand edit or commit the top-level files in #{config}# containing #{LB_*}# variables, as these are build products, too, and are always cleaned up by #{lb clean}# and re-created with #{lb config}# via their respective #{auto}# scripts. +[875][para] +We've come to the end of our tutorial series. While many more kinds of customization are possible, even just using the few features explored in these simple examples, an almost infinite variety of different images can be created. The remaining examples in this section cover several other use cases drawn from the collected experiences of users of live systems. +[876][heading] +A VNC Kiosk Client +[877][para] +*{Use case:}* Create an image with live-build to boot directly to a VNC server. +[878][para] +Make a build directory and create an skeletal configuration inside it, disabling recommends to make a minimal system. And then create two initial package lists: the first one generated with a script provided by live-build named #{Packages}# (see {Generated package lists}#generated-package-lists), and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and /{xvnc4viewer}/. +[879][code] + + $$ mkdir vnc-kiosk-client + $$ cd vnc-kiosk-client + $$ lb config -a i386 -k 686-pae --apt-recommends false + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $$ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + + +[880][para] +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you may need to re-add some recommended packages to make your image work properly. +[881][para] +An easy way to list recommends is using /{apt-cache}/. For example: +[882][code] + + $$ apt-cache depends live-config live-boot + + +[883][para] +In this example we found out that we had to re-include several packages recommended by live-config and live-boot: #{user-setup}# to make autologin work and #{sudo}# as an essential program to shutdown the system. Besides, it could be handy to add #{live-tools}# to be able to copy the image to RAM and #{eject}# to eventually eject the live medium. So: +[884][code] + + $$ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + + +[885][para] +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# and put a custom #{.xsession}# in it for the default user that will launch /{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a server at #{192.168.1.2}#: +[886][code] + + $$ mkdir -p config/includes.chroot/etc/skel + $$ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + + +[887][para] +Build the image: +[888][code] + + # lb build + + +[889][para] +Enjoy. +[890][heading] +A base image for a 128MB USB key +[891][para] +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. +[892][para] +When optimizing an image to fit a certain media size, you need to understand the tradeoffs you are making between size and functionality. In this example, we trim only so much as to make room for additional material within a 128MB media size, but without doing anything to destroy the integrity of the packages contained within, such as the purging of locale data via the /{localepurge}/ package, or other such "intrusive" optimizations. Of particular note, we use #{--debootstrap-options}# to create a minimal system from scratch. +[893][code] + + $$ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + + +[894][para] +To make the image work properly, we must re-add, at least, two recommended packages which are left out by the #{--apt-recommends false}# option. See {Tweaking APT to save space}#tweaking-apt-to-save-space +[895][code] + + $$ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + + +[896][para] +Now, build the image in the usual way: +[897][code] + + # lb build 2>&1 | tee build.log + + +[898][para] +On the author's system at the time of writing this, the above configuration produced a 110MB image. This compares favourably with the 192MB image produced by the default configuration in {Tutorial 1}#tutorial-1. +[899][para] +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount of space, the tradeoff being that you need to do an #{apt-get update}# before using /{apt}/ in the live system. Dropping recommended packages with #{--apt-recommends false}# saves some additional space, at the expense of omitting some packages you might otherwise expect to be there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal system from the start. Not automatically including firmware packages with #{--firmware-chroot false}# saves some space too. And finally, #{--memtest none}# prevents the installation of a memory tester. +[900][para] +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. +[901][heading] +A localized GNOME desktop and installer +[902][para] +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. +[903][para] +We want to make an iso-hybrid image for i386 architecture using our preferred desktop, in this case GNOME, containing all of the same packages that would be installed by the standard Debian installer for GNOME. +[904][para] +Our initial problem is the discovery of the names of the appropriate language tasks. Currently, live-build cannot help with this. While we might get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, which can be used to dig it out of the task descriptions in tasksel-data, so to prepare, make sure you have both of those things: +[905][code] + + # apt-get install dctrl-tools tasksel-data + + +[906][para] +Now we can search for the appropriate tasks, first with: +[907][code] + + $$ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + + +[908][para] +By this command, we discover the task is called, plainly enough, german. Now to find the related tasks: +[909][code] + + $$ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + + +[910][para] +At boot time we will generate the *{de_CH.UTF-8}* locale and select the *{ch}* keyboard layout. Now let's put the pieces together. Recalling from {Using metapackages}#using-metapackages that task metapackages are prefixed #{task-}#, we just specify these language boot parameters, then add standard priority packages and all our discovered task metapackages to our package list as follows: +[911][code] + + $$ mkdir live-gnome-ch + $$ cd live-gnome-ch + $$ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $$ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $$ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $$ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + + +[912][para] +Note that we have included the /{debian-installer-launcher}/ package to launch the installer from the live desktop. The #{586}# kernel flavour, which is currently necessary for the launcher to work properly, will be included by default. +[913][heading] +Appendix +[914][heading] +Style guide +[915][heading] +Style guide +[916][heading] +Guidelines for authors +[917][para] +This section deals with some general considerations to be taken into account when writing technical documentation for live-manual. They are divided into linguistic features and recommended procedures. +[918][para] +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute +[919][heading] +Linguistic features +[920][para] +_* /{Use plain English}/ +[921][para] +Keep in mind that a high percentage of your readers are not native speakers of English. So as a general rule try to use short, meaningful sentences, followed by a full stop. +[922][para] +This does not mean that you have to use a simplistic, naive style. It is a suggestion to try to avoid, as much as possible, complex subordinate sentences that make the text difficult to understand for non-native speakers of English. +[923][para] +_* /{Variety of English}/ +[924][para] +The most widely spread varieties of English are British and American so it is very likely that most authors will use either one or the other. In a collaborative environment, the ideal variety would be "International English" but it is very difficult, not to say impossible, to decide on which variety among all the existing ones, is the best to use. +[925][para] +We expect that different varieties may mix without creating misunderstandings but in general terms you should try to be coherent and before deciding on using British, American or any other English flavour at your discretion, please take a look at how other people write and try to imitate them. +[926][para] +_* /{Be balanced}/ +[927][para] +Do not be biased. Avoid including references to ideologies completely unrelated to live-manual. Technical writing should be as neutral as possible. It is in the very nature of scientific writing. +[928][para] +_* /{Be politically correct}/ +[929][para] +Try to avoid sexist language as much as possible. If you need to make references to the third person singular preferably use "they" rather than "he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. +[930][para] +_* /{Be concise}/ +[931][para] +Go straight to the point and do not wander around aimlessly. Give as much information as necessary but do not give more information than necessary, this is to say, do not explain unnecessary details. Your readers are intelligent. Presume some previous knowledge on their part. +[932][para] +_* /{Minimize translation work}/ +[933][para] +Keep in mind that whatever you write will have to be translated into several other languages. This implies that a number of people will have to do an extra work if you add useless or redundant information. +[934][para] +_* /{Be coherent}/ +[935][para] +As suggested before, it is almost impossible to standardize a collaborative document into a perfectly unified whole. However, every effort on your side to write in a coherent way with the rest of the authors will be appreciated. +[936][para] +_* /{Be cohesive}/ +[937][para] +Use as many text-forming devices as necessary to make your text cohesive and unambiguous. (Text-forming devices are linguistic markers such as connectors). +[938][para] +_* /{Be descriptive}/ +[939][para] +It is preferable to describe the point in one or several paragraphs than merely using a number of sentences in a typical "changelog" style. Describe it! Your readers will appreciate it. +[940][para] +_* /{Dictionary}/ +[941][para] +Look up the meaning of words in a dictionary or encyclopedia if you do not know how to express certain concepts in English. But keep in mind that a dictionary can either be your best friend or can turn into your worst enemy if you do not know how to use it correctly. +[942][para] +English has the largest vocabulary that exists (with over one million words). Many of these words are borrowings from other languages. When looking up the meaning of words in a bilingual dictionary the tendency of a non-native speaker of English is to choose the one that sounds more similar in their mother tongue. This often turns into an excessively formal discourse which does not sound quite natural in English. +[943][para] +As a general rule, if a concept can be expressed using different synonyms, it is a good advice to choose the first word proposed by the dictionary. If in doubt, choosing words of Germanic origin (Usually monosyllabic words) is often the right thing to do. Be warned that these two techniques might produce a rather informal discourse but at least your choice of words will be of wide use and generally accepted. +[944][para] +Using a dictionary of collocations is recommended. They are extremely helpful when it comes to know which words usually occur together. +[945][para] +Again it is a good practice to learn from the work of others. Using a search engine to check how other authors use certain expressions may help a lot. +[946][para] +_* /{False friends, idioms and other idiomatic expressions}/ +[947][para] +Watch out for false friends. No matter how proficient you are in a foreign language you cannot help falling from time to time in the trap of the so called "false friends", words that look similar in two languages but whose meanings or uses might be completely different. +[948][para] +Try to avoid idioms as much as possible. "Idioms" are expressions that may convey a completely different meaning from what their individual words seem to mean. Sometimes, idioms might be difficult to understand even for native speakers of English! +[949][para] +_* /{Avoid slang, abbreviations, contractions...}/ +[950][para] +Even though you are encouraged to use plain, everyday English, technical writing belongs to the formal register of the language. +[951][para] +Try to avoid slang, unusual abbreviations that are difficult to understand and above all contractions that try to imitate the spoken language. Not to mention typical irc and family friendly expressions. +[952][heading] +Procedures +[953][para] +_* /{Test before write}/ +[954][para] +It is important that authors test their examples before adding them to live-manual to ensure that everything works as described. Testing on a clean chroot or VM can be a good starting point. Besides, it would be ideal if the tests were then carried out on different machines with different hardware to spot possible problems that may arise. +[955][para] +_* /{Examples}/ +[956][para] +When providing an example try to be as specific as you can. An example is, after all, just an example. +[957][para] +It is often better to use a line that only applies to a specific case than using abstractions that may confuse your readers. In this case you can provide a brief explanation of the effects of the proposed example. +[958][para] +There may be some exceptions when the example suggests using some potentially dangerous commands that, if misused, may cause data loss or other similar undesirable effects. In this case you should provide a thorough explanation of the possible side effects. +[959][para] +_* /{External links}/ +[960][para] +Links to external sites should only be used when the information on those sites is crucial when it comes to understanding a special point. Even so, try to use links to external sites as sparsely as possible. Internet links are likely to change from time to time resulting in broken links and leaving your arguments in an incomplete state. +[961][para] +Besides, people who read the manual offline will not have the chance to follow those links. +[962][para] +_* /{Avoid branding and things that violate the license under which the manual is published}/ +[963][para] +Try to avoid branding as much as possible. Keep in mind that other downstream projects might make use of the documentation you write. So you are complicating things for them if you add certain specific material. +[964][para] +live-manual is licensed under the GNU GPL. This has a number of implications that apply to the distribution of the material (of any kind, including copyrighted graphics or logos) that is published with it. +[965][para] +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ +[966][para] +- Brainstorm!. You need to organize your ideas first in a logical sequence of events. +[967][para] +- Once you have somehow organized those ideas in your mind write a first draft. +[968][para] +- Revise grammar, syntax and spelling. Keep in mind that the proper names of the releases, such as $${testing} or sid, should not be capitalized when referred to as code names. In order to check the spelling you can run the "spell" target. i.e. #{make spell}# +[969][para] +- Improve your statements and redo any part if necessary. +[970][para] +_* /{Chapters}/ +[971][para] +Use the conventional numbering system for chapters and subtitles. e.g. 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup below. +[972][para] +If you have to enumerate a series of steps or stages in your description, you can also use ordinal numbers: First, second, third ... or First, Then, After that, Finally ... Alternatively you can use bulleted items. +[973][para] +_* /{Markup}/ +[974][para] +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to process the text files and produce a multiple format output. It is recommended to take a look at {SiSU's manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get familiar with its markup, or else type: +[975][code] + + $$ sisu --help markup + + +[976][para] +Here are some markup examples that may prove useful: +[977][para] +- For emphasis/bold text: +[978][code] + +*{foo}* or !{foo}! + + +[979][para] +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. +[980][para] +- For italics: +[981][code] + +/{foo}/ + + +[982][para] +produces: /{foo}/. Use them e.g. for the names of Debian packages. +[983][para] +- For monospace: +[984][code] + +#{foo}# + + +[985][para] +produces: #{foo}#. Use it e.g. for the names of commands. And also to highlight some key words or things like paths. +[986][para] +- For code blocks: +[987][code] + + code{ + + $$ foo + # bar + + }code + + +[988][para] +produces: +[989][code] + + $$ foo + # bar + + +[990][para] +Use #{code{}# to open and #{}code}# to close the tags. It is important to remember to leave a space at the beginning of each line of code. +[991][heading] +Guidelines for translators +[992][para] +This section deals with some general considerations to be taken into account when translating the contents of live-manual. +[993][para] +As a general recommendation, translators should have read and understood the translation rules that apply to their specific languages. Usually, translation groups and mailing lists provide information on how to produce translated work that complies with Debian quality standards. +[994][para] +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation +[995][heading] +Translation hints +[996][para] +_* /{Comments}/ +[997][para] +The role of the translator is to convey as faithfully as possible the meaning of words, sentences, paragraphs and texts as written by the original authors into their target language. +[998][para] +So they should refrain from adding personal comments or extra bits of information of their own. If they want to add a comment for other translators working on the same documents, they can leave it in the space reserved for that. That is, the header of the strings in the *{po}* files preceded by a number sign *{#}*. Most graphical translation programs can automatically handle those types of comments. +[999][para] +_* /{TN, Translator's Note}/ +[1000][para] +It is perfectly acceptable however, to include a word or an expression in brackets in the translated text if, and only if, that makes the meaning of a difficult word or expression clearer to the reader. Inside the brackets the translator should make evident that the addition was theirs using the abbreviation "TN" or "Translator's Note". +[1001][para] +_* /{Impersonal sentences}/ +[1002][para] +Documents written in English make an extensive use of the impersonal form "you". In some other languages that do not share this characteristic, this might give the false impression that the original texts are directly addressing the reader when they are actually not doing so. Translators must be aware of that fact and reflect it in their language as accurately as possible. +[1003][para] +_* /{False friends}/ +[1004][para] +The trap of "false friends" explained before especially applies to translators. Double check the meaning of suspicious false friends if in doubt. +[1005][para] +_* /{Markup}/ +[1006][para] +Translators working initially with *{pot}* files and later on with *{po}* files will find many markup features in the strings. They can translate the text anyway, as long as it is translatable, but it is extremely important that they use exactly the same markup as the original English version. +[1007][para] +_* /{Code blocks}/ +[1008][para] +Even though the code blocks are usually untranslatable, including them in the translation is the only way to score a 100% complete translation. And even though it means more work at first because it might require the intervention of the translators if the code changes, it is the best way, in the long run, to identify what has already been translated and what has not when checking the integrity of the .po files. +[1009][para] +_* /{Newlines}/ +[1010][para] +The translated texts need to have the exact same newlines as the original texts. Be careful to press the "Enter" key or type *{\n}* if they appear in the original files. These newlines often appear, for instance, in the code blocks. +[1011][para] +Make no mistake, this does not mean that the translated text needs to have the same length as the English version. That is nearly impossible. +[1012][para] +_* /{Untranslatable strings}/ +[1013][para] +Translators should never translate: +[1014][para] +- The code names of releases (which should be written in lowercase) +[1015][para] +- The names of programs +[1016][para] +- The commands given as examples +[1017][para] +- Metadata (often between colons *{:metadata:}*) +[1018][para] +- Links +[1019][para] +- Paths +[1019][heading] +Endnotes +[1020][heading] +Endnotes +[1021][heading] +Book Index +[1022][heading] +Index +[92m-------------------------------[0m +en/live-manual.ssm +length contents array: 1026 +last obj_cite_number: 1022 +length bookindex: 0 +lib/sdp/ao_output_debugs.d:293 +processed file: en/live-manual.ssm +[92m~ document complete, ok ~[0m +[36m~ run complete, ok ~ [0m (sdp-1.0.0, Digital Mars D v2071, 64 bit Linux) diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/about_manual.ssi new file mode 100644 index 0000000..f218db4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/about_manual.ssi @@ -0,0 +1,284 @@ +:B~ O tym podręczniku + +1~about-manual O tym podręczniku + +This manual serves as a single access point to all documentation related to +the ${project} and in particular applies to the software produced by the +project for the Debian 9.0 "${stable}" release. An up-to-date version can +always be found at http://live-systems.org/ + +Podczas, gdy podręcznik live-manual skupia się przede wszystkim na pomocy w +budowaniu systemu live, a nie na tematach użytkownika końcowego. To +użytkownik końcowy również może znaleźć przydatne informacje w następujących +sekcjach: {Podstawy}#the-basics obejmuje pobieranie skompilowanych obrazów i +przygotowanie obrazów tak aby były uruchamiany z nośnika przenośnego lub z +sieci, równocześnie używanie web builder lub uruchamianie live-build +bezpośrednio w systemie. {Dostosowywanie zachowania w czasie działania +systemu}#customizing-run-time-behaviours opisuje kilka opcji, które mogą +zostać określone podczas startu, na przykład wybieranie układu klawiatury i +ustawienia regionalne, używając opcji persistence. + +Niektóre z poleceń zawartych w tekście muszą być wykonywane z uprawnieniami +superużytkownika, które mogą być uzyskane przez stanie się użytkownikiem +root poprzez #{su}# lub używając #{sudo}#. Aby odróżnić te polecenia, które +mogą być wykonywane przez nieuprzywilejowanego użytkownika i te wymagające +praw administratora, polecenia zostały poprzedzone przez odpowiednio by +#{$}# or #{#}# . Symbol ten nie jest częścią polecenia. + +2~ Dla niecierpliwych + +Wierzymy, że wszystko w tym podręczniku jest ważne, przynajmniej dla +niektórych z naszych użytkowników. Zdajemy sobie sprawę również, że zawiera +on dużo materiału do sprostania. I że może chciałbyś doświadczyć szybkich +postępów w używaniu oprogramowania przed zagłębianiem się w +szczegóły. Dlatego sugerujemy czytanie w następującej kolejności. + +Najpierw przeczytaj rozdział, {O tym podręczniku}#about-manual, od początku, +kończąc na sekcji {Warunki}#terms. Następnie przejdź do trzech ćwiczeń na +początku sekcji {Przykłady}#examples mającej na celu nauczyć Cię podstaw +budowania obrazu i dostosowywania. Najpierw przeczytaj {Używanie +przykładów}#using-the-examples, następnie {Tutorial 1: Domyślny +obraz}#tutorial-1, {Tutorial 2: Narzędzie przeglądarka}#tutorial-2 i +wreszcie {Tutorial 3: Spersonalizowany obraz}#tutorial-3. Pod koniec tych +tutoriali, będziesz mieć ogólny zarys tego, co można zrobić z systemami +live. + +Zachęcamy do powrotu i bardziej dogłębnej analizy podręcznika, być może +następnym razem czytanie {Podstaw}#the-basics, przejrzenie lub pominięcie +{Budowanie obrazu netboot}#building-netboot-image, a skończywszy czytając +{Omówienie dostosowywania}#customization-overview i rozdziałów, które po nim +następują. W tym momencie, mamy nadzieję, że są zostałeś zainteresowany tym, +co można zrobić z systemami live i zmotywowany, aby przeczytać resztę tego +podręcznika, od deski do deski. + +2~terms Definicje + +_* *{System live}*: System operacyjny, który można uruchomić bez instalacji +na dysku twardym. Systemy live nie zmieniają lokalnego systemu(-ów) lub +pliku(-ów) już zainstalowany na dysku twardym komputera, chyba że zostało to +specjalnie ustawione. Systemy live są zwykle uruchamiane z nośników takich +jak płyty CD, DVD lub pamięci USB. Niektóre mogą się także uruchamiać z +sieci (za pośrednictwem obrazów netboot, patrz {Budowanie obrazu +netboot}#building-netboot-image) i przez Internet (za pomocą parametru +startowego #{fetch=URL}#, patrz {Webbooting}#webbooting). webbooting). + +_* *{Nośnik live}*: W odróżnieniu od systemu live, nośnik live odnosi się do +dysku CD, DVD lub pamięci USB, gdzie znajdują się pliki binarne stworzone +przez live-build, które są używane do uruchamiania systemu live. Szerzej, +termin ten odnosi się również do każdego miejsca, w którym znajdują się te +pliki binarne, które są potrzebne do uruchomienia systemu live, również +takich miejsc jak miejsca dla plików startowych w sieci. + +_* *{${project}}*: Projekt, który dostarcza, między innymi pakiety: +live-boot, live-build, live-config, live-tools i live-manual. + +_* *{System hosta}*: Środowisko użyte do stworzenia systemu live. + +_* *{System docelowy}*: Środowisko użyte do uruchomienia systemu live. + +_* *{live-boot}*: Zbiór skryptów wykorzystywanych do uruchamiania systemów +live. + +_* *{live-build}*: Zbiór skryptów wykorzystywanych do budowy +niestandardowych systemów live. + +_* *{live-config}*: Zbiór skryptów używane do konfiguracji systemu live w +czasie procesu bootowania. + +_* *{live-tools}*: Zbiór dodatkowych skryptów wykorzystywanych do +wykonywania pożytecznych zadań w ramach uruchomionego systemu live. + +_* *{live-manual}*: Dokument ten jest tworzony w pakiecie o nazwie +live-manual. + +_* *{Debian Installer (d-i)}*: Oficjalny system instalacyjny dystrybucji +Debian. + +_* *{Parametry startowe}*: Parametry, które mogą być wprowadzone w wierszu +bootloadera, aby wpłynąć na jądro lub live-config. + +_* *{chroot}*: Program /{chroot}/, #{chroot(8)}#, pozwala na uruchomienie +różnych instancji środowiska GNU / Linux na jednym systemie bez ponownego +uruchomiania go. + +_* *{Obraz binarny}*: Plik zawierający system live, takie jak +live-image-i386.hybrid.iso lub live-image-i386.img. + +_* *{Dystrybucja docelowa}*: dystrybucja, na której opierać się będzie +system żywo. To może się różnić od dystrybucji systemu hosta. + +_* *{stable/testing/unstable}*: Dystrybucja *{stable}*, obecnia nazwa kodowa +to ${stable}, zawiera najnowsze oficjalnie wydanie dystrybucji +Debian. Dystrybucja *{testing}*, tymczasowo nadana nazwa kodowa to +${testing}, to obszar postoju przed następnym wydaniem *{stable}*. Główną +zaletą korzystania z tej dystrybucji jest to, że zawiera nowsze wersje +oprogramowania w stosunku do wydania *{stable}*. Dystrybucja *{unstable}*, +trwale nazwana sid, to ta gdzie zachodzi aktywny rozwój Debian. Ogólnie +rzecz biorąc, to dystrybucja prowadzona jest przez deweloperów i tych, +którzy lubią życie na krawędzi. W tym podręczniku, mamy tendencję do +korzystania z nazw kodowych wydań, takich jak ${testing} lub sid, bo głównie +w tych wydaniach jest zawarte to co aktualnie zawierają narzędzia same w +sobie. + +2~ Autorzy + +Lista Autorów (w kolejności alfabetycznej): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Wnoszenie wkładu do tego dokumentu + +Intencją niniejszy podręcznik jest dziłanie jako projekt społeczny, a więc +wszelkie propozycje usprawnień i zmian są bardzo mile widziane. Proszę +przejrzyj sekcję {Przyczynianie się do projektu}#contributing-to-project w +celu uzyskania szczegółowych informacje na temat sposobu pobrania klucza do +wysyłania zmian i jak wnosić dobre zmiany. + +3~applying-changes Nanoszenie zmian + +W celu dokonania zmian w podręczniku angielskim musisz edytować odpowiednie +pliki w #{manual/en/}#, ale przed złożeniem swojego wkładu, należy przejrzeć +swoją pracę. Aby wyświetlić podgląd live-manual, upewnij się, że pakiety +potrzebne do budowy to są zainstalowane przez wykonanie: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Możesz zbudować live-manual z głównego katalogu swojego zapytania GIT przez +wykonanie: + +code{ + + $ make build + +}code + +Ponieważ zbudowanie podręcznika we wszystkich obsługiwanych językach zajmuje +trochę czasu, autorzy mogą zdecydować, że wygodniej będzie skorzystać z +jednego z szybko korygujących skrótów podczas zamieszczania nowej +dokumentacji, którą dodali do podręcznika angielskiego. Używanie #{PROOF=1}# +tworzy live-manual w formacie HTML, ale bez posegmentowanych plików HTML, a +przy użyciu #{PROOF=2}# tworzy się live-manual w formacie PDF, ale tylko +sformatowane jako A4 i listowy pionowy. Dlatego korzystając z jednej z +możliwości opcji #{PROOF=}# można zaoszczędzić sporo czasu, np.: + +code{ + + $ make build PROOF=1 + +}code + +Gdy zatwierdzasz jedno z tłumaczeń możliwe jest zbudowanie tylko dla jednego +języka, przez wykonanie, np.: + +code{ + + $ make build LANGUAGES=pl + +}code + +Jest też możliwe, aby zbudować po typie dokumentu, np: + +code{ + + $ make build FORMATS=pdf + +}code + +Lub kombinacja obu, np: + +code{ + + $ make build LANGUAGES=pl FORMATS=html + +}code + +Po rewizji swojej pracy i upewnieniu się, że wszystko jest w porządku, nie +należy używać #{make commit}# chyba aktualizujesz już istniejące +tłumaczenia, i w tym przypadku, nie należy mieszać zmian do instrukcji +angielskiej i tłumaczeń w tej samej wysłanej zmianie, ale należy użyć +osobnych zgłoszeń zmian dla każdego tłumaczenia. Zobacz sekcję +{Tłumaczenie}#translation, aby uzyskać więcej szczegółów. + +3~translation Tłumaczenie + +W celu przetłumaczenia live-manual, wykonaj następujące kroki, w zależności +od tego, czy rozpoczynasz tłumaczenie od zera czy też kontynuujesz pracę na +już istniejącym tłumaczeniu: + +_* Rozpocznij nowe tłumaczenie od zera + +_2* Przetłumacz pliki *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* i +*{index.html.in.pot}* w #{manual/pot/}# na swój język używając swojego +ulubionego edytora (np. /{poedit}/) i wyślij przetłumaczony plik #{.po}# do +listy mailingowej, aby sprawdzić ich integralność. Sprawdzanie integralności +live-manual sprawdza, nie tylko czy pliki #{.po}# są w 100% przetłumaczone, +ale również wykrywa ewentualne błędy. + +_2* Po sprawdzeniu, aby włączyć nowy język w autobuild to wystarczy dodać +początkowo przetłumaczone pliki do #{manual/po/${LANGUAGE}/}# i uruchomić +#{make commit}#. A następnie, edytować #{manual/_sisu/home/index.html}# +dodając nazwę języka i jego nazwy w języku angielskim w nawiasach. + +_* Kontynuuj pracę z już rozpoczętym tłumaczeniem + +_2* Jeśli Twój język docelowy został już dodany, można losowo kontynuować +tłumaczenia pozostałych plików .po w #{manual/po/${LANGUAGE}/}# za pomocą +dowolnego edytora (np. /{poedit}/). + +_2* Nie zapomnij, że musisz uruchomić #{make commit}# w celu zapewnienia, że +przetłumaczone podręczniki są aktualizowane z plików .po i że możesz +przeglądać swoje zmiany uruchomamiając #{make build}# przed #{git add .}#, +następnie #{git commit -m "Translating..."}# (Tłumaczenie...) i #{git +push}#. Pamiętaj, że polecenie #{make build}# może zająć dużo czasu, możesz +wybrać indywidualnie korygowane języki jak wyjaśniono w {Zatwierdzanie +zmian}#applying-changes + +Po uruchomieniu #{make commit}# zobaczysz jakiś przewijający się tekst. Są +to przede wszystkim informacyjne komunikaty o statusie przetwarzania, a +także niektóre wskazówki na temat tego, co mogłoby być zrobione, aby +poprawić live-manual. Chyba, że widzisz błąd krytyczny, zazwyczaj w takim +wypadku możesz kontynuować i wysłać swój wkład w tłumaczenie. + +live-manual składa się z dwóch narzędzi, które mogą w znacznym stopniu pomóc +tłumaczom znaleźć nieprzetłumaczone i zmienione ciągi znaków. Pierwszy z +nich jest "make translate". Uruchamia skrypt, który mówi dokładnie ile nie +przetłumaczonych ciągów jest w każdym pliku .po. Drugi, "make fixfuzzy", +działa tylko na zmienionych ciągach znaków, ale to pomaga znaleźć je i +edytować jeden po drugim. + +Należy pamiętać, że nawet jeśli te narzędzia mogą być bardzo pomocne do +pracy z tłumaczeniami w linii poleceń, to korzystanie z wyspecjalizowanego +narzędzia jak /{poedit}/ jest zalecanym sposobem, aby wykonać zadanie. Jest +to również dobry pomysł, aby zapoznać się z dokumentacjami Debian o +lokalizacjach (l10n) i tymi specyficznymi dla live-manual: {Poradnik dla +tłumaczy}#guidelines-translators. + +*{Uwaga:}* Możesz użyć #{make clean}# aby oczyścić swoje drzewo git przed zamieszczeniem. Ten krok nie jest obowiązkowy, dzięki plikowi .gitignore, ale dobrą praktyką jest uniknać zatwierdzania plików odruchowo. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/about_project.ssi new file mode 100644 index 0000000..af79acf --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/about_project.ssi @@ -0,0 +1,105 @@ +:B~ O ${project} + +1~about-project O ${project} + +2~ Motywacja + +3~ Co jest nie tak w moim dotychczasowym systemie live? + +Gdy ${project} został zainicjowany, było już dostępnych kilka systemów live +opartych na Debianie i które teraz świetnie się spisują. Z punktu widzenia +Debian większość z nich ma jednak jedną lub więcej z następujących wad: + +_* Nie są to projekty Debian i dlatego nie posiadają także wsparcia ze +strony Debian. + +_* Mieszają rózne dystrybucje, np.: *{testing}* i *{unstable}*. + +_* Wspierają tylko i386. + +_* Modyfikują zachowanie i/lub wygląd pakietów przez obcinanie ich w celu +zaoszczędzenia miejsca. + +_* Zawierają pakiety z poza archiwum Debian. + +_ * Są dostarczane z jądrem systemu zawierającym dodatkowe łaty, które nie +są częścią Debian. + +_* Są duże i powolne a ze względu na swoją zwykłą wielkość, a zatem nie +nadają się do zagadnień odzyskiwania. + +_* Nie są one dostępne na różnych nośnikach, np. CD, DVD, USB-stick czy +obrazy netboot. + +3~ Czemu tworzyć nasz własny system live? + +Debian to Uniwersalny system operacyjny: Debian będzie posiadał system live +do przetestowania i dokładnego zaprezentowania systemu Debian z +następującymi głównymi zaletami: + +_* Będzie pod-projektem Debian. + +_* Będzie odzwierciedlał stan aktualnej dystrybucji. + +_* Będzie wspierał tak wiele architektur jak to tylko możliwe. + +_* Będzie się składał tylko z niezmienionych pakietów Debian. + +_* Nie będzie zawierał żadnych pakietów, które nie są w archiwum Debian. + +_* Będzie korzystał z niezmienionego jądro Debian bez dodatkowych poprawek. + +2~ Filozofia + +3~ Tylko niezmienione pakiety z działu Debian "main" + +Będziemy używać tylko pakietów z repozytorium Debian w sekcji "main". Sekcja +"non-free" nie jest częścią Debian, a zatem nie może być używana do +budowania oficjalnych obrazów systemu live. + +Nie będziemy zmieniać żadnych pakietów. Zawsze, gdy będziemy musieli coś +zmienić, zrobimy to w porozumieniu z opiekunem tego pakietu w Debianie. + +W drodze wyjątku, nasze własne pakiety, takie jak live-boot, live-build lub +live-config mogą być zastosowane tymczasowo z własnego repozytorium z +przyczyn rozwojowych (np. do tworzenia zrzutów rozwojowych). Zostaną one +przesłane do Debian na bieżąco. + +3~ Bez konfiguracji pakietów systemu live + + Na tym etapie nie będziemy dostarczać lub też instalować przykładowych lub +alternatywnych konfiguracji pakietów. Wszystkie pakiety będą użyte w u ich +podstawowych konfiguracjach takich jakie są po normalnej instalacji Debian. + +Za każdym razem, gdy potrzebujemy innej domyślnej konfiguracji, zrobimy to w +porozumieniu z opiekunem pakietu w Debianie. + +System do konfigurowania pakietów jest dostarczony przez użycie debconf'a; +umożliwiając instalację niestandardowo skonfigurowanych pakietów w Twoim +niestandardowo stworzonym obrazie systemu live. A dla {prekompilowanych +obrazów live}#downloading-prebuilt-images zdecydowaliśmy, aby pozostawić +pakiety w swojej domyślnej konfiguracji, chyba że będzie to absolutnie +niezbędne do pracy w środowisku live. Wszędzie tam, gdzie to możliwe, wolimy +dostosowywać pakiety w archiwum Debian, aby lepiej pracowały w systemie live +w porównaniu do dokonywania zmian w live toolchain lub {konfiguracji obrazu +prekompilownego} # klonuj-konfiguracja-przez-git. Aby uzyskać więcej +informacji, zobacz {Omówienie dostosowywania}#customization-overview. + +2~contact Kontakt + +_* *{Lista Mailingowa}*: Podstawowym kontaktem do projektu jest lista +mailingowa na https://lists.debian.org/debian-live/. Możesz napisać do listy +bezpośrednio przez zadresowanie poczty do +debian-live@lists.debian.org. Archiwa listy dostępne są na +https://lists.debian.org/debian-live/. + +_* *{IRC}*: Wielu użytkowników i deweloperów jest obecnych na kanale +#debian-live na irc.debian.org (OFTC). Kiedy zadajesz pytanie na IRC, +prosimy o cierpliwie czekać na odpowiedź. W przypadku, gdy odpowiedz nie +pojawi się, napisz na listę mailingową. + +_* *{BTS}*: {Debian Bug Tracking System} https://www.debian.org/Bugs/ (BTS) +zawiera informacje o błędach zgłoszonych przez użytkowników i +deweloperów. Każdy błąd ma przypisany swój numer i jest przechowywany, +dopóki nie zostaje on oznaczony jako rozwiązany. Aby uzyskać więcej +informacji, zobacz {Zgłaszanie błędów}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/appendix_style-guide.ssi new file mode 100644 index 0000000..f55a491 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/appendix_style-guide.ssi @@ -0,0 +1,371 @@ +:B~ Przewodnik redakcyjny + +1~style-guide Przewodnik redakcyjny + +2~ Wytyczne dla autorów + +Ten rozdział zajmuje się pewnymi ogólnymi rozważaniami, które należy wziąć +pod uwagę podczas pisania dokumentacji technicznej dla live-instrukcji. Są +one podzielone na funkcje językowe oraz zalecane procedury. + +*{Uwaga:}* Autorzy powinni najpierw przeczytać {Współtworzenie tego dokumentu}#how-to-contribute + +3~ Funkcje językowe + +_* /{Użyj zwykłego angielskiego}/ + +Należy pamiętać, że wysoki procent czytelników nie są rodzimymi +użytkownikami języka angielskiego. Więc jako generalną zasadę spróbuj używać +krótkich, sensownych zdań, zakończonych kropką. + +To nie znaczy, że trzeba korzystać z uproszczonego, naiwnego +stylu. Proponuje się unikać, na ile to możliwe, złożonych zdań podrzędnych, +które czynią tekst trudny do zrozumienia dla nie rodzimych użytkowników +języka angielskiego. + +_* /{Różnorodność języka angielskiego}/ + +The most widely spread varieties of English are British and American so it +is very likely that most authors will use either one or the other. In a +collaborative environment, the ideal variety would be "International +English" but it is very difficult, not to say impossible, to decide on which +variety among all the existing ones, is the best to use. + +Spodziewamy się, że różne odmiany języka mogą mieszać się bez tworzenia +nieporozumień, ale ogólnie należy starać się być spójnym i przed podjęciem +decyzji o użyciu brytyjskiego, amerykańskiego lub innego dialektu języka +angielskiego wedle uznania, proszę przyjrzeć się, jak inni ludzie piszą i +postarać się ich naśladować. + +_* /{Bądź zbalansowany}/ + +Nie być stronniczy. Unikaj w tym odniesienia do ideologii zupełnie +niepowiązanych z live-manual. Pismo techniczne powinny być możliwie jak +najbardziej neutralne. Jak to jest w naturze piśmiennictwa naukowego. + +_* /{Bądź poprawny politycznie}/ + +Staraj się unikać seksistowskiego języka, jak to jest tylko możliwe. Jeśli +potrzebujesz, odwołania do trzeciej osoby liczby pojedynczej najlepiej użyć +jakiejś formy bezosobowej lub "wy" zamiast "on" , "ona" lub niewygodnych +wynalazków, takie jak "mógłbyś/mogłabyś", "byłem/łam" i podobnych. + +_* /{Bądz zwięzły}/ + +Go straight to the point and do not wander around aimlessly. Give as much +information as necessary but do not give more information than necessary, +this is to say, do not explain unnecessary details. Your readers are +intelligent. Presume some previous knowledge on their part. + +_* /{Oszczędź pracy tłumaczącym}/ + +Należy pamiętać, że cokolwiek napiszesz będzie musiało zostać przetłumaczone +na kilka innych języków. Oznacza to, że sporo osób, będzie musiał wykonać +dodatkową pracę jeśli dodasz bezużyteczne lub nadmiarowe informacje. + +_* /{Bądź zgodny}/ + +As suggested before, it is almost impossible to standardize a collaborative +document into a perfectly unified whole. However, every effort on your side +to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be spójny}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Bądź opisowy}/ + +It is preferable to describe the point in one or several paragraphs than +merely using a number of sentences in a typical "changelog" style. Describe +it! Your readers will appreciate it. + +_* /{Słownik}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not +know how to express certain concepts in English. But keep in mind that a +dictionary can either be your best friend or can turn into your worst enemy +if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million +words). Many of these words are borrowings from other languages. When +looking up the meaning of words in a bilingual dictionary the tendency of a +non-native speaker of English is to choose the one that sounds more similar +in their mother tongue. This often turns into an excessively formal +discourse which does not sound quite natural in English. + +Zgodnie z ogólną zasadą, jeśli koncepcja może być wyrażony za pomocą różnych +synonimów to dobrą radą będzie wybieranie pierwszego słowa zaproponowanego +przez słownik. W razie wątpliwości, często słusznym jest wybieranie słowa +pochodzenia germańskiego (zwykle jednosylabowe słowa). Ostrzegamy, że te +dwie techniki, mogą produkować raczej mowę nieformalną, ale przynajmniej +wybór słów będzie o szerokim zastosowaniu i ogólnie przyjęty. + +Korzystanie ze słownika kolokacji jest zalecane. Są one bardzo pomocne, +kiedy przychodzi do znajomości słów najczęściej występujących razem. + +Ponownie; dobrą praktyką jest, aby uczyć się z pracy innych. Korzystanie z +wyszukiwarki, aby sprawdzić, jak inni autorzy mogą korzystać z niektórych +wyrażeń może bardzo pomóc. + +_* /{Fałszywi przyjaciele, idiomy i inne wyrażenia idiomatyczne}/ + +Uważaj na fałszywych przyjaciół. Bez względu na to, jak biegły jesteś w +obcym języku nie można pomóc wpadając od czasu do czasu w pułapkę tzw. +"fałszywych przyjaciół", słowa, które wyglądają podobnie w dwóch językach, +ale których znaczenie lub zastosowanie może być zupełnie inne. + +Staraj się unikać idiomów w jak największym stopniu. "Idiomy" to wyrażenia, +które mogą mieć znaczenie zupełnie odmienne od tego, co ich poszczególne +słowa wydają się oznaczać. Czasami, idiomy, mogą być trudne do zrozumienia +nawet dla rodzimych użytkowników języka angielskiego! + +_* /{Unikaj slangu, skrótów, mowy potocznej...}/ + +Nawet jeśli popierasz korzystanie ze zwykłego, codziennego języka +angielskiego, pisanie techniczne należy do formalnej formy języka. + +Staraj się unikać slangu, niepopularnych skrótów, które są trudne do +zrozumienia, a przede wszystkim skrótów, które próbują naśladować język +mówiony. Nie wspominając o typowych dla kanałów IRC i przyjaznych dla +zamkniętych gron wyrażeń. + +3~ Procedury + +_* /{Przetestuj przed zapisaniem}/ + +It is important that authors test their examples before adding them to +live-manual to ensure that everything works as described. Testing on a clean +chroot or VM can be a good starting point. Besides, it would be ideal if the +tests were then carried out on different machines with different hardware to +spot possible problems that may arise. + +_* /{Przykłady}/ + +W przypadku dostarczania przykładu spróbuj być tak dokładny jak tylko +możesz. Przykład jest, mimo wszystko, tylko przykładem. + +It is often better to use a line that only applies to a specific case than +using abstractions that may confuse your readers. In this case you can +provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some +potentially dangerous commands that, if misused, may cause data loss or +other similar undesirable effects. In this case you should provide a +thorough explanation of the possible side effects. + +_* /{Linki zewnętrzne}/ + +Links to external sites should only be used when the information on those +sites is crucial when it comes to understanding a special point. Even so, +try to use links to external sites as sparsely as possible. Internet links +are likely to change from time to time resulting in broken links and leaving +your arguments in an incomplete state. + +Poza tym, ludzie, którzy czytają instrukcję w trybie offline nie będą mogli +śledzić tych linków. + +_* /{Unikaj nadawania marki i rzeczy, które naruszają licencję zgodnie z +którą podręcznik ten został opublikowany}/ + +Try to avoid branding as much as possible. Keep in mind that other +downstream projects might make use of the documentation you write. So you +are complicating things for them if you add certain specific material. + +live-manual jest oparty na licencji GNU GPL. Ma to wiele skutków, które +odnoszą się do redystrybucji materiału (dowolnego rodzaju, w tym grafiki +chronionej prawami autorskimi lub logo), który jest opublikowany wraz nim. + +_* /{Napisz pierwszy szkic, przeglądnij go, edytuj, popraw i cofnij zmiany +jeżeli wymaga tego sytuacja}/ + + - Burza mózgów!. Najpierw musisz zorganizować swoje pomysły w logicznej + kolejności zdarzeń. + + - Kiedy już w jakiś sposób masz zorganizowane te koncepcje w głowie napisz + pierwszy szkic. + + - Dokonaj przeglądu gramatyki, składni i pisowni. Należy pamiętać, że + właściwe nazwy wydań, takich jak ${testing} lub sid nie powinny być + kapitalizowane, gdy odnosi się do nich jako nazw kodowych. Aby sprawdzić + pisownię można uruchomić cel "spell". tj. polecenie #{make spell}# + + - Udoskonalaj swoje wyrażenia, a jeśli to konieczne cofnij i przerób każdą + część. + +_* /{Rozdziały}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, +1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup +below. + +If you have to enumerate a series of steps or stages in your description, +you can also use ordinal numbers: First, second, third ... or First, Then, +After that, Finally ... Alternatively you can use bulleted items. + +_* /{Znaczniki}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to +process the text files and produce a multiple format output. It is +recommended to take a look at {SiSU's +manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get +familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +To są przykłady znaczników, które mogą okazać się użyteczne: + + - Dla pogrubienia użyj: + +code{ + +*{foo}* lub !{foo}! + +}code + +powoduje: *{foo}* lub !{foo}!. Użyj tego by wyszczególnić określone słowa +kluczowe. + + - Dla kursywy użyj: + +code{ + +/{foo}/ + +}code + +powoduje: /{foo}/. Użyj tego dla np. nazw paczek Debiana. + + - Dla czcionki o stałej szerokości użyj: + +code{ + +#{foo}# + +}code + +powoduje: #{foo}#. Użyj tego np. dla nazw poleceń. A także aby uwidocznić +poszczególne słowa kluczowe jak ścieżki dostępowe. + + - Dla bloków z kodem użyj: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +powoduje: + +code{ + + $ foo + # bar + +}code + +Użyj #{code{}# do otwarcia i #{}code# do zamknięcia tagu. Ważne jest, aby +pamiętać, by zostawić miejsce na początku każdej linii kodu. + +2~guidelines-translators Wytyczne dla tłumaczy + +Ta sekcja zajmuje się pewnymi ogólnymi rozważaniami, które należy wziąć pod +uwagę przy tłumaczeniu zawartości live-manual. + +Jako ogólne zalecenie, tłumacze powinni przeczytać i zrozumieć zasady +tłumaczenia, które mają zastosowanie do ich specyficznych +języków. Zazwyczaj, grupy i listy dyskusyjne tłumaczeń dostarczają +informacji o tym, jak tworzyć przetłumaczone pracę zgodne z normami jakości +Debiana. + +*{Uwaga:}* Tłumacze powinni również przeczytać {Współtworzenie tego dokumentu}#how-to-contribute. W szczególności rozdział {Tłumaczenie}#translation + +3~ Wskazówki tłumaczenia + +_* /{Komentarze}/ + +The role of the translator is to convey as faithfully as possible the +meaning of words, sentences, paragraphs and texts as written by the original +authors into their target language. + +So they should refrain from adding personal comments or extra bits of +information of their own. If they want to add a comment for other +translators working on the same documents, they can leave it in the space +reserved for that. That is, the header of the strings in the *{po}* files +preceded by a number sign *{#}*. Most graphical translation programs can +automatically handle those types of comments. + +_* /{UT, Uwagi Tłumacza}/ + +It is perfectly acceptable however, to include a word or an expression in +brackets in the translated text if, and only if, that makes the meaning of a +difficult word or expression clearer to the reader. Inside the brackets the +translator should make evident that the addition was theirs using the +abbreviation "TN" or "Translator's Note". + +_* /{Wyrażenia w trybie bezosobowym}/ + +Documents written in English make an extensive use of the impersonal form +"you". In some other languages that do not share this characteristic, this +might give the false impression that the original texts are directly +addressing the reader when they are actually not doing so. Translators must +be aware of that fact and reflect it in their language as accurately as +possible. + +_* /{Fałszywi przyjaciele}/ + +Pułapka "fałszywych przyjaciół" wyjaśnionych wcześniej szczególnie dotyczy +tłumaczy. Dwukrotnie sprawdzić znaczenie podejrzanych fałszywych przyjaciół +w razie wątpliwości. + +_* /{Znaczniki}/ + +Tłumacze pracujący początkowo nad plikami *{pot}*, a później z plikami *{po} +* znajdą wiele znaczników w ciągach. Mogą oni przetłumaczyć tekst tak, jak +to jest tylko możliwe do tłumaczenia, ale niezwykle ważnym jest, aby używali +oni dokładnie takich samych znaczników jak w oryginalnej wersji angielskiej. + +_* /{Bloki kodowe}/ + +Mimo, że bloki z kodem są zazwyczaj nieprzetłumaczalne, zawarcie ich w +tłumaczeniach jest jedynym sposobem, aby zdobyć 100% kompletne +tłumaczenie. I mimo, że oznacza to więcej pracy na początku, bo to może +wymagać interwencji od tłumaczy jeśli kod się zmieni, to jest to najlepszy +sposób, w dłuższej perspektywie czasu na określenie, co już zostało +przetłumaczone, a co nie podczas sprawdzania integralności plików .po. + +_* /{Nowe linijki}/ + +Przetłumaczone teksty muszą mieć te same znaki nowej linii jak teksty +oryginalne. Należy uważać, aby nacisnąć klawisz "Enter" lub wpisać *{\n}* +jeśli pojawią się one w oryginalnych plików. Znaki te często pojawiają się, +na przykład, w blokach z kodem. + +Nie popełniaj błedów, to nie znaczy, że przetłumaczony tekst musi mieć taką +samą długość jak w wersji angielskiej. Jest to prawie niemożliwe. + +_* /{Nieprzetłumaczalne ciągi znaków}/ + +Tłumacze nigdy nie powinni tłumaczyć: + + - Nazw kodowych wydań (które powinny być pisane małymi literami) + + - Nazw programów + + - Komend podanych jako przykład + + - Metadanych (zazwyczaj pomiędzy dwukropkami *{:metadata:}*) + + - Linków + + - Ścieżek dostępnowych diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/examples.ssi new file mode 100644 index 0000000..54b41a3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/examples.ssi @@ -0,0 +1,452 @@ +:B~ Przykłady + +1~examples Przykłady + +W tym rozdziale omówiono przykłady budowania dla konkretnych przypadków +użycia z systemów live. Jeśli jesteś nowy w budowaniu własnych obrazów +systemów live, zaleca się najpierw zapoznanie z trzema kolejnymi +samouczkami, a każdy z nich nauczy Cię nowych technik, które pomogą Ci +używać i rozumieć pozostałe przykłady. + +2~using-the-examples Używanie przykładów + +Aby skorzystać z tych przykładów potrzebujesz systemu, który spełnia +wymagania wymienione w {wymaganiach}#requirements i ma zainstalowane +live-build, jak opisano w {instalacji live-build}#installing-live-build. + +Należy zauważyć, że, ze względu na zwięzłość, w tych przykładach nie +określono lokalnego serwera używanego do kompilacji. Można znacznie +przyspieszyć pobrań przypadku korzystania z lokalnego serwera +lustrzanego. Można określić te opcje podczas korzystania z #{lb config}#, +jak opisano w {Serwery lustrzane dystrybucji używane w czasie +kompilacji}#distribution-mirrors-build-time lub dla większej wygody, ustawić +domyślną opcję dla systemu kompilacji w #{/etc/live/build.conf}#. Wystarczy +utworzyć ten plik, a w nim, ustawić odpowiednią zmienną #{LB_MIRROR_*}# dla +preferowanego serwera lustrzanego. Wszystkie inne serwery lustrzane +stosowane podczas kompilacji, będą domyślnie ustawione od tych wartości. Na +przykład: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 Samouczek 1: Domyślny obraz + +*{Przykład użycia:}* Stwórz pierwszy prosty obraz aby nauczyć się podstaw live-build. + +W tym samouczku, będziemy budować domyślny obraz live ISO-hybrid zawierający +tylko pakiety podstawowe (bez Xorg'a) i kilka pakietów systemu live, jako +pierwsze ćwiczenie w użyciu live-build. + +Nie można tego zrobić łatwiej niż tak: + +code{ + + $ mkdir samouczek1 ; cd samouczek1 ; lb config + +}code + + Zbadaj zawartość katalogu #{config/}#, jeśli chcesz. Zobaczysz tam +konfiguracje przechowywane w szkieletowych katalogach, gotowe do +dostosowywania lub, w tym przypadku, użyte natychmiast, aby zbudować +domyślny obraz. + +A teraz jako super-użytkownik, zbuduj obraz zapisując przy tym log podczas +budowania używając #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Zakładając, że wszystko poszło dobrze, po jakimś czasie, bieżący katalog +będzie zawierał #{live-image-i386.hybrid.iso}#. Ten hybrydowy obraz ISO +można uruchomić bezpośrednio na maszynie wirtualnej, jak opisano w +{Testowanie obrazu ISO z Qemu}#testing-iso-with-qemu i {Testowanie obrazu +ISO z VirtualBox}#testing-iso-with-virtualbox, lub jeszcze odpowiednio +nagrany obraz na nośnikach optycznych lub urządzenia flash USB, w sposób +opisany w {Nagrywanie obrazu ISO na nośniku fizycznym}#burning-iso-image i +{Kopiowanie hybrydowego obrazu ISO na nośnik USB}#copying-iso-hybrid-to-usb. + +2~tutorial-2 Samouczek 2: Narzędzie przeglądarka + +*{Przykład użycia:}* Stwórz obraz z przeglądarką internetową, ucząc się jak wprowadzać modyfikacje. + +W tym samouczku, stworzymy obraz odpowiedni do wykorzystania jako narzędzie +przeglądarki internetowej, służący jako wstęp do dostosowywania obrazów +systemu live. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Nasz wybór LXDE na tym przykładzie odzwierciedla nasze pragnienie, aby +zapewnić minimalne środowisko pulpitu, ponieważ celem obrazu jest +jednorazowy użytek, który mamy na myśli, czyli przeglądarka +internetowa. Możemy pójść dalej i zapewnić domyślną konfigurację dla +przeglądarki w #{config/includes.chroot/etc/iceweasel/profile/}#, lub +dodatkowe pakiety wsparcia dla wyświetlania różnego rodzaju treści +internetowych, ale pozostawiamy to jako ćwiczenie dla czytelnika. + +Zbuduj ponownie obraz jako super-użytkownik, zachowując log jak to opisano w +{Samouczku 1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Jeszcze raz, zweryfikuj czy obraz jest OK i przetestuj go jak to opisano w +{Samouczku 1}#tutorial-1. + +2~tutorial-3 Samouczek 3: Spersonalizowany obraz + +*{Przykład użycia:}* Stwórz projekt spersonalizowanego obrazu zawierającego twoje ulubione oprogramowanie tak abyś mógł go zabrać ze sobą gdziekolwiek pójdziesz i zapisujący sukcesywnie zmiany, kiedy tego potrzebujesz oraz zmiany w konfiguracji. + +Ponieważ będziemy zmieniać nasz indywidualny obraz wprowadzając wiele zmian, +chcemy, śledzić te zmiany, próbując rzeczy eksperymentalnych i ewentualnie +przywracając je, jeśli coś nie wyjdzie, będziemy trzymać naszą konfigurację +w popularnym systemie kontroli wersji #{git}#. Będziemy również +wykorzystywać najlepsze praktyki autokonfiguracji poprzez skrypty #{auto}# +jak opisano w {Zarządzanie konfiguracją}#managing-a-configuration. + +3~ Pierwsza zmiana + +code{ + + $ mkdir -p samouczek3/auto + $ cp /usr/share/doc/live-build/examples/auto/* samouczek3/auto/ + $ cd samouczek3 + +}code + +Edtuj #{auto/config}# tak, aby zawierał: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Wykonaj #{lb config}#, aby wygenerować drzewo konfiguracyjne, używając +właśnie utworzonego skryptu w #{auto/config}#: + +code{ + + $ lb config + +}code + +Teraz uzupełnij swoją lokalną listę pakietów: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +Po pierwsze, #{--architectures i386}# zapewnia, że w naszym systemie +kompilacji #{amd64}#, możemy zbudować 32-bitową wersję odpowiednią do +stosowania na większości maszyn. Po drugie, możemy użyć #{--linux-flavours +686-pae}# bo nie przewidujemy używania tego obrazu na dużo starszych +systemach. Po trzecie, wybraliśmy metapakiet zadania /{lxde}/, który daje +nam minimalny pulpit. I w końcu, dodaliśmy dwa wstępne ulubione pakiety: +/{iceweasel}/ i /{xchat}/. + +A teraz, zbuduj obraz: + +code{ + + # lb build + +}code + +Należy zauważyć, że w przeciwieństwie do dwóch pierwszych samouczków, nie +musimy już wpisywać #{2>&1 | tee build.log}# bo jest to obecnie zawarte w +#{auto/build}#. + +Po tym jak przetestowaliśmy obraz (jak to jest w {Samouczku 1}#tutorial-1) i +jesteśmy zadowoleni, że działa, to jest to czas, aby zainicjować nasze +repozytorium #{git}#, dodając tylko automatyczne skrypty przed chwilą +stworzone, a następnie dokonać pierwszych zmian: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Druga zmiana + +W tej zmianie, będziemy sprzątać nasz pierwszy zbudowany obrazu, dodawać +pakiet /{vlc}/ do naszej konfiguracji, budować ponownie, testować i +potwierdzać zmiany. + +Polecenie #{lb clean}# oczyści wszystkie wygenerowane pliki z poprzedniej +kompilacji z wyjątkiem pamięci podręcznej (cache), co oszczędza konieczności +ponownego pobierania pakietów. To gwarantuje, że kolejne polecenie #{lb +build}# ponownie uruchomić wszystkie etapy regeneracji pliki z naszej nowej +konfiguracji. + +code{ + + # lb clean + +}code + +Teraz dołączpakiet /{vlc}/ do naszej lokalnej listy pakietów w +#{config/package-list/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Zbuduj ponownie: + +code{ + +# lb build + +}code + +Przetestuj i jeżeli jesteś usatysfakcjonowany wprowadź następną zmianę: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Oczywiście, możliwe są bardziej skomplikowane zmiany w konfiguracji, +prawdopodobnie dodające pliki w podkatalogach #{config/}#. Kiedy wprowadzasz +nowe zmiany , tylko uważaj, aby nie edytować ręcznie lub zmieniać plików +najwyższego poziomu w #{config}# zawierających zmienną #{LB_*}#, ponieważ są +to także efekty budowania i są zawsze sprzątane przez #{lb clean}# i +tworzone ponownie przez #{lb config}# przez odpowiednie #{automatyczne}# +skrypty. + +Doszliśmy do końca naszej serii samouczka. Chociaż możliwe jest o wiele +więcej rodzajów personalizacji, nawet tylko za pomocą kilku funkcji +pokazanych w tych prostych przykładach, może być stworzona niemal +nieskończona różnorodność obrazów. Pozostałe przykłady w tym rozdziale +obejmuje kilka innych przypadków użycia zaczerpnięte z zebranych doświadczeń +użytkowników systemów live. + +2~ Kiosk-klient serwera VNC + +*{Przykład użycia:}* Stwórz obraz za pomocą live-build, który podczas uruchamiania, łączy się automatycznie z serwerem VNC. + +Stwórz katalog kompilacji i stwórz wewnątrz szkielet folderów konfiguracji, +wyłączając zalecane, aby utworzyć minimalny system. A następnie utwórz dwie +początkowe listy pakietów: pierwszą wygenerowaną ze skryptu dostarczonego +przez live-build o nazwie #{Pakiety}# (patrz {Wygenerowane listy +pakietów}#generated-package-lists), a drugą uwzględniającą pakiety /{xorg}/, +/{gdm3}/, /{metacity}/ i /{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +Jak wyjaśniono w {Podkręcanie APT, w celu zaoszczędzenia +miejsca}#tweaking-apt-to-save-space może trzeba ponownie dodać niektóre +polecane pakiety do prawidłowej pracy obrazu. + +Najprostszym sposobem na wypisane listy rekomendowanych pakietów jest u +życie /{apt-cache}/. Na przykład: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +W tym przykładzie okazało się, że musimy ponownie objąć kilka pakietów +zalecanych przez live-config i live-boot: #{user-setup}# do funkcji +autologowania i #{sudo}# jako istotnego przy zamykaniu systemu +programu. Poza tym, może być przydatne, również dodanie #{live-tools}#, aby +móc skopiować obraz systemu do pamięci RAM i #{eject}#, aby ewentualnie +wysunąć nośnik live. Tak więc: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +Po tym, stwórz katalog #{/etc/skel}# w #{config/includes.chroot}# i umieść +tam własny #{.xsession}# dla domyślnego użytkownika, który będzie uruchamiał +/{metacity}/ i /{xvncviewer}/, podłączając się do portu #{5901}# na serwerze +w #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Zbuduj obraz: + +code{ + + # lb build + +}code + +Korzystaj. + +2~ Bazowy obraz dla nośnika USB z 128MB pamięci. + +*{Przykład użycia:}* Stwórz domyślny obraz z usuniętymi niektórymi komponentami tak, aby zmieścił się on na nośniku USB z 128MB pamięci z pozostawieniem niewielkiej przestrzeni do wykorzystania według potrzeb. + +Przy optymalizacji obrazu, aby dopasować go do określonego rozmiaru nośnika, +musisz dokonać pewnych kompromisów między rozmiarem a funkcjonalnością. W +tym przykładzie, przytniemy tylko tyle, aby zrobić miejsce dla dodatkowego +materiału medialnego w rozmiarze 128MB, ale robienia czegokolwiek, co +mogłoby zniszczyć integralność zawartych pakietów, np. czyszczenie danych +ustawień regionalnych poprzez pakiet /{localepurge}/, lub inne tego typu +/{inwazyjne}/ optymalizacje. Szczególnie godne uwagi, jest użycie +#{--debootstrap-options}# by stworzyć minimalny system od podstaw. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +Aby uczynić by obraz pracował prawidłowo, musimy ponownie dodać przynajmniej +dwa pakiety, które zostały pominięte przez opcję #{--apt-recommends +false}#. Zobacz {Podkręcanie APT w celu zaoszczędzenia +miejsca}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Teraz, zbuduj obraz w typowy sposób: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration +produced a 110MB image. This compares favourably with the 192MB image +produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount +of space, the tradeoff being that you need to do an #{apt-get update}# +before using /{apt}/ in the live system. Dropping recommended packages with +#{--apt-recommends false}# saves some additional space, at the expense of +omitting some packages you might otherwise expect to be +there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal +system from the start. Not automatically including firmware packages with +#{--firmware-chroot false}# saves some space too. And finally, #{--memtest +none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ Pulpit GNOME w lokalnym języku oraz instalator + +*{Przykład użycia:}* Stwórz obraz z pulpitem GNOME i lokalizacją dla Szwajcarii wraz z instalatorem. + +Chcemy stworzyć obraz ISO-hybrydy dla architektury i386 z naszym +preferowanym pulpitem, w tym przypadku GNOME, zawierającą wszystkie pakiety, +które byłyby zainstalowane przez standardowy instalator Debiana dla GNOME. + +Naszym początkowym problem jest odkrycie nazw odpowiednich zadań +językowych. Obecnie, live-build nie może nam w tym pomóc. Chociaż możemy +mieć szczęście i znaleźć to metodą prób i błędów, to jest narzędzie, +#{grep-dctrl}#, które może być użyte do ustalenia to z opisów zadań w +tasksel-data tak więc, aby przygotować się upewnij się, że masz obie te +rzeczy: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Teraz możemy rozpocząć wyszukiwanie odpowiedniego zadania. najpierw: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +Dzięki temu poleceniu dowiadujemy się, że zadanie nazywa się po prostu +niemiecki (ang. german). Teraz, aby znaleźć podobne zadania: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +W czasie startu systemu będziemy generować lokalizację *{de_CH.UTF-8}* i +wybierać układ klawiatury *{ch}*. Teraz poskładajmy kawałki +razem. Przypominamy sobie {Korzystanie z metapakietów}#using-metapackages +że metapakiety są poprzedzone przedrostkiem #{task-}#, po prostu określimy +te parametry rozruchowe dotyczące języka, a następnie dodamy standardowe +pakiety priorytetowe i wszystkie wykryte metapakiety zadań do naszej listy +pakietów w następujący sposób: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to +launch the installer from the live desktop. The #{586}# kernel flavour, +which is currently necessary for the launcher to work properly, will be +included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/pl/live-manual.ssm new file mode 100644 index 0000000..294209f --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Podręcznik Systemów Live" + +creator: + author: "Projekt Systemów Live<debian-live@lists.debian.org>" + +rights: + copyright: "Copyright (C) 2006-2015 Projekt Systemów Live" + license: "Ten program jest wolnym oprogramowaniem: możesz go rozprowadzać dalej i / lub modyfikować zgodnie z warunkami Powszechnej Licencji Publicznej GNU opublikowanej przez Free Software Foundation, według wersji 3 tej Licencji lub (według Twojego wyboru) dowolnej późniejszej wersji \\ \\ Ten program jest rozpowszechniany w nadziei, że będzie użyteczny, ale BEZ JAKIEJKOLWIEK GWARANCJI; bez nawet domyślnej gwarancji PRZYDATNOŚCI HANDLOWEJ albo PRZYDATNOŚCI DO OKREŚLONYCH ZASTOSOWAŃ. Patrz GNU General Public License aby uzyskać więcej szczegółów. \\ \\ Powinieneś otrzymać kopię Licencji GNU General Public License wraz z tym programem. Jeśli nie, odwiedź http://www.gnu.org/licenses/. \\ \\ Pełny tekst licencji GNU General Public można znaleźć w pliku /usr/share/common-licenses/GPL-3." + +date: + published: "2015-08-23" + +publisher: "Projekt Systemów Live<debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ O tym podręczniku + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Użytkownik + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Projekt + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Przykłady + +<< examples.ssi + +:B~ Dodatek + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/project_bugs.ssi new file mode 100644 index 0000000..1128d50 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/project_bugs.ssi @@ -0,0 +1,217 @@ +:B~ Zgłaszanie błędów + +1~bugs Zgłaszanie błędów + +Systemy live są dalekie od doskonałości, ale chcemy, uczynić je jak +najbliższe perfekcji - z Waszą pomocą. Nie wahaj się zgłosić błąd. Lepiej +jest wypełnić raport dwa razy niż wcale. Ten rozdział zawiera zalecenia +dotyczące sposobu składania raportów o błędach. + +Dla niecierpliwych: + +_* Zawsze należy sprawdzić najpierw aktualizacje statusu obrazu na naszej +stronie internetowej http://live-systems.org/, w poszukiwaniu znanych +problemów. + +_* Przed wysłaniem raportu o błędzie zawsze spróbuj odtworzyć problem z +*{najnowszą wersją}* gałęzi live-build, live-boot, live-config i live-tools, +których używasz (jak najnowsza wersja 4.x live-build, jeśli używasz +live-build 4). + +_* Spróbuj podać *{jak najwięcej specyficznych informacji, jak to tylko +możliwe}* o błędzie. Obejmuje to (co najmniej) wersję używanych live-build, +live-boot, live-config i live-tools oraz dystrybucję systemu live którą +kompilujesz. + +2~ Znane problemy + +Ponieważ Debian *{testing} * i Debian *{unstable}* dystrybucjami ruchomymi, +w przypadku określenia jednej z nich jako dystrybucji systemu docelowego, +kompilowanie nie zawsze zakończy się sukcesem. + +% FIXME: + +Jeśli budowanie systemu opartego na *{testing}* lub *{unstable}* powoduje u +Ciebie zbyt wiele trudności, raczej wykorzystaj wydanie +*{stable}*. live-build zawsze ustawia domyślnie wydanie *{stable}*. + +Obecnie znane problemy wymienione są w ramach sekcji "status" na naszej +stronie internetowej w http://live-systems.org/. + +To jest poza zakresem tej instrukcji, aby szkolić się poprawnie +identyfikować i naprawiać problemy pakietów z dystrybucji rozwojowych, +jednak istnieją dwie rzeczy, których zawsze można spróbować: Jeśli +kompilowanie nie powiedzie się, gdy docelową dystrybucją jest *{testing}*, +to spróbuj z *{unstable}*. Jeśli *{unstable}* również nie działa, to +przywróć do dystrybucji *{testing}* i przypnij nowszą wersję wadliwego +pakietu z wersji *{unstable}* (patrz {Przypinanie APT}#apt-pinning aby +uzyskać szczegóły). + +2~ Przebuduj od zera + +Aby upewnić się, że dany błąd nie jest spowodowany nie w pełni wyczyszczonym +budowanym systemem, proszę zawsze odbudować cały system live od podstaw, aby +sprawdzić, czy błąd jest powtarzalny. + +2~ Używaj aktualnych pakietów + +Używanie przestarzałych pakietów może powodować poważne problemy podczas +próby odtworzenia (i ostatecznego rozwiązania) problemu. Upewnij się, że +system na którym kompilujesz jest aktualny i wszelkie pakiety zawarte w +obrazie również. + +2~collect-information Zbierz potrzebne informacje + +Proszę dostarczyć wystarczającą ilość informacji z raportem. Obejmujące co +najmniej, dokładną wersję live-build, gdzie napotkano błąd i kroki, jak go +odtworzyć. Proszę użyć zdrowego rozsądku i przedstawić wszelkie inne istotne +informacje, jeśli uważasz, że może to pomóc w rozwiązaniu problemu. + +Aby w pełni wykorzystać Twój raport o błędzie, będziemy potrzebować +przynajmniej następujących informacji: + +_* Architektura systemu hosta + +_* Dystrybucja systemu hosta + +_* Wersja live-build na systemie hosta + +_* Version of /{debootstrap}/ on the host system + +_* Architektura systemu live + +_* Dystrybucja systemu live + +_* Wersja live-boot na systemie live + +_* Wersja live-config na systemie live + +_* Wersja live-tools na systemie live + +Można wygenerować log procesu kompilacji przy użyciu polecenia +#{tee}#. Polecamy robić to automatycznie przy użyciu skryptu #{auto/build}# +(patrz {Zarządzanie konfiguracją}#managing-a-configuration w celu uzyskania +szczegółów). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +W czasie uruchamiania live-boot i live-config przetrzymują swoje logi w +#{/var/log/live/}#. Sprawdź je w poszukiwaniu błędów. + +Dodatkowo, aby wykluczyć inne błędy, zawsze dobrym pomysłem jest, aby +spakować do archiwum tar swój katalog #{config/}# i przesłać go gdzieś +(*{nie}* należy wysłać go jako załącznik do listy), tak aby można spróbować +odtworzyć napotkane błędy. Jeśli sprawia to trudność (np. ze względu na +rozmiar) można użyć wyjścia z polecenia #{lb config --dump}#, które tworzy +podsumowanie drzewa konfiguracyjnego (czyli np. listę plików w podkatalogach +#{config/}#, ale bez załączania ich). + +Pamiętaj, aby wysłać wszystkie dzienniki i logi, które zostały wyprodukowane +z ustawień regionalnych angielskich, np. uruchom polecenia live-build ze +zmiennymi #{LC_ALL=C}# lub #{LC_ALL=en_US}#. + +2~ Wyizoluj prawdopodobną wadę, jeśli to możliwe + +Jeśli to możliwe, należy wyizolować przypadek do najmniejszej zmiany, które +generuje błąd. Nie zawsze jest łatwo to zrobić, więc jeśli nie możesz dodać +takiej informacji do raportu, nie martw się. Jednakże, jeśli użytkownik +dobrze planuje swój cykl rozwoju, przy użyciu małych zestawów zmian na +iterację, można być w stanie wyizolować problem poprzez budowę prostszej +konfiguracji "bazy", która blisko pasuje do rzeczywistej konfiguracji oraz +tylko uszkodzony zestaw zmian do niej dodany. Jeśli masz trudności z +sortowaniem, które z Twoich zmian wygenerowały błąd, może to znaczyć, że +uwzględniono za dużo w każdym zestawie zmian i powinno się raczej kształcić +w mniejszych krokach. + +2~ Wybierz odpowiedni pakiet dla którego zgłaszasz błąd + +Jeśli nie wiesz, który komponent jest odpowiedzialny za błąd, lub jeśli błąd +jest ogólnym błędem dotyczącym systemów live, można wypełnić raport błędu +dotyczący pseudo-pakietu debian-live. + +Jednak będziemy wdzięczni, jeśli postarasz się zawęzić pole możliwości, w +których może pojawiać się błąd. + +3~ W czasie budowania podczas ładowania początkowego (bootstrapping) + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a +bug appears here, check if the error is related to a specific Debian package +(most likely), or if it is related to the bootstrapping tool itself. + +W obu przypadkach nie jest to błąd w systemie live, ale w samym Debianie i +prawdopodobnie nie możemy naprawić go bezpośrednio. Proszę zgłosić taki błąd +jako dotyczący narzędzia ładowania początkowego (ang. bootstraping tool) lub +uszkodzonego pakietu. + +3~ W czasie budowania podczas instalacji pakietów + +live-build instaluje dodatkowe pakiety z archiwum Debiana i w zależności od +używanej dystrybucji Debian i codziennego stanu archiwum, może się to nie +powieść. Jeśli błąd pojawi się w tym miejscu, należy sprawdzić, czy błąd +jest powtarzalny w normalnym systemie. + +Jeśli jest to przypadek, gdzie błąd nie występuje w systemie live, ale w +Debianie - zgłoś go jako dotyczący wadliwego pakietu. Uruchomienie +/{debootstrap}/ niezależnie od samej kompilacji systemu live lub +uruchomianie #{lb bootstrap - debug}# daje więcej informacji. + +Ponadto, w przypadku korzystania z lokalnego serwera lustrzanego i/lub +jakichkolwiek serwerów proxy i doświadczania problemów prosimy zawsze +najpierw spróbować odtworzyć czyności z użyciem oficjalnego serwera +lustrzanego. + +3~ W czasie uruchamiania + +Jeśli obraz nie uruchamia się, należy zgłosić go do listy wraz z +informacjami wymaganymi w {Zbierz potrzebne +informacje}#collect-information. Nie zapomnij wspomnieć, jak/kiedy dokładnie +obraz nie zadziałał, czy był użyty za pomocą wirtualizacji lub rzeczywistego +sprzętu. Jeśli korzystasz z technologii wirtualizacji w jakiejkolwiek +formie, proszę zawsze uruchomić go na prawdziwym sprzęcie przed zgłoszeniem +błędu. Zapewnienie zrzutu ekranu awarii jest również bardzo pomocne. + +3~ W czasie gdy system jest już uruchomiony + +Jeśli pakiet został zainstalowany, ale nie działa gdy system live faktycznie +działa, jest to prawdopodobnie błąd w systemie live. Jednakże: + +2~ Spróbuj wykonać parę kroków + +Przed zgłoszeniem błędu, proszę poszukaj w internecie danego komunikatu o +błędzie lub objawu jaki otrzymujesz. Ponieważ jest mało prawdopodobne, że +jesteś jedyną osobą, która zmaga się ze szczególnym problem. Zawsze jest +szansa, że został on już omówiony w innym miejscu i zaproponowano już +możliwe rozwiązanie, obejście lub patch. + +Należy zwrócić szczególną uwagę na listę mailingową systemów live, jak +również strona główna, ponieważ zawierają one prawdopodobnie najbardziej +aktualne informacje. Jeśli takowa informacja istnieje, zawsze należy zawrzeć +odniesienie do niej w swoim raporcie o błędzie. + +Ponadto, należy sprawdzić aktualne wykazy błędów dla live-build, live-boot, +live-config i live-tools, aby zobaczyć, czy coś podobnego nie zostało już +zgłoszone. + +2~ Gdzie zgłaszać błędy + +${project} śledzi wszystkie błędy w systemie śledzenia błędów (BTS). Aby +uzyskać informacje na temat korzystania z tego systemu, zobacz +https://bugs.debian.org/. Możesz też przesłać błędy używając polecenia +#{reportbug} z pakietu o tej samej nazwie. + +Ogólnie rzecz biorąc, należy zgłaszać błędy podczas kompilacji: jako +dotyczące pakietu live-build, błędy podczas uruchamiania: live-boot oraz +błędy w czasie działania systemu live: jako dotyczące live-config. Jeśli nie +jesteś pewien, który pakiet będzie odpowiedni lub potrzebujesz więcej +pomocy, przed złożeniem zgłoszenia błędu, zgłoś raport dotyczący +pseudo-pakietu debian-live. Zajmiemy się wtedy nim i przypiszemy do +odpowiedniego pakietu. + +Należy pamiętać, że błędy znalezione w dystrybucji pochodzących od Debiana +(takich jak Ubuntu, i inne) *{nie}* powinny być zgłaszane do BTS Debiana, +chyba że błędy te mogą być odtworzone w Debianie przy użyciu oficjalnych +pakietów Debiana. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/project_coding-style.ssi new file mode 100644 index 0000000..7c90dca --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/project_coding-style.ssi @@ -0,0 +1,151 @@ +:B~ Styl Kodowania + +1~coding-style Styl Kodowania + +Rozdział ten dokumentuje styl kodowania używany w systemach live. + +2~ Kompatybilność + +_* Nie wolno używać składni lub semantyki, które jest unikalne dla basha. Na +przykład, użycie układu konstrukcji. + +_* Nie używaj podzbiorów POSIX'a - na przykład, używaj $(foo) zamiast`foo`. + +_* Możesz sprawdzić swoje skrypty używając 'sh -n' i 'checkbashisms'. + +_* Upewnij się, że cały kod powłoki działa z 'set-e'. + +2~ Wcięcia + +_* Zawsze używaj tabulatorów zamiast spacji. + +2~ Zawijanie + +_* Generalnie linie mają maksymalnie 80 znaków. + +_* Używaj zakończeń lini "typowych dla Linuxa": + +Źle: + +code{ + + if foo; then + bar + fi + +}code + +Dobrze: + +code{ + + if foo + then + bar + fi + +}code + +_* To samo dotyczy funkcji: + +Źle: + +code{ + + Foo () { + bar + } + +}code + +Dobrze: + +code{ + +Foo () + { + bar + } + +}code + +2~ Zmienne + +_* Zmienne występują zawsze zapisane drukowanymi literami. + +_* Zmienne wykorzystane w live-build zawsze zaczynają się przedroskiem +#{LB_}#. + +_* Wewnętrzne tymczasowe zmienne w live-build należy rozpocząć od +przedrostka #{\_LB_}#. + +_* Lokalne zmienne zaczynają się przedrostkiem live-build'a #{\_\_LB_}#. + +_* Zmienne dotyczące parametrów startowych live-config zaczynają się od +#{LIVE_}#. + +_* Wszystkie inne zmienne w live-config zacznij przedroskiem #{_}#. + +_* Używaj nawiasów wokół zmiennych; na przykład napisz #{${FOO}}# zamiast +#{$FOO}#. + +_* Zawsze chroń zmienne znakami cytatu do zachowania potencjalnych białych +znaków: napisz #{"${FOO}"}#, a nie #{${FOO}}#. + +_ * Dla zachowania spójności, należy zawsze używać znaków cytatu podczas +przypisywania wartości do zmiennych: + +Źle: + +code{ + + FOO=bar + +}code + +Dobrze: + +code{ + + FOO="bar" + +}code + +_* Jeśli zastosowane jest wiele zmiennych, przytocz całe wyrażenie: + +Źle: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Dobrze: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Różne + +_* Używaj "#{|}#" (bez otaczających wyrażenie znaków cytatu) jako +rozdzielacz w zapytania do sed'a, np. "#{sed -e 's|foo|bar|'}#" (bez ""). + +_* Nie używaj komendy #{test}# dla porównań i testów, użyj "#{[}#" "#{]}#" +(bez ""); np. "#{if [ -x /bin/foo ]; ...}#" a nie "#{if test -x /bin/foo; +...}#". + +_ * Użyj #{case}# gdzie to jest możliwe zamiast #{test}#, jest to łatwiejsze +do odczytania i szybsze w wykonaniu. + +_* Użyj nazw funkcji pisanych wielkimi literami, aby ograniczyć niepożądane +działanie e środowisku użytkownika. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/project_contributing.ssi new file mode 100644 index 0000000..e881cd5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/project_contributing.ssi @@ -0,0 +1,119 @@ +:B~ Wnoszenie wkładu do tego projektu + +1~contributing-to-project Wnoszenie wkładu do tego projektu + +Wnosząc swój wkład należy jasno określić posiadacza jego praw autorskich i +zawrzeć wszelkie stosowane oświadczenie licencjonowania. Należy pamiętać, że +aby zmiany były zaakceptowane, wkład musi być licencjonowany na tej samej +licencji co reszta dokumentów, a mianowicie, GPL w wersji 3 lub nowszej. + +Wkład do projektu, taki jak tłumaczenia i poprawki, są bardzo mile +widziane. Każdy może bezpośrednio zaangażować się w repozytoriach, jednak +prosimy wysłać większe zmiany do listy mailingowej, aby omówić je w +pierwszej kolejności. Patrz rozdział {kontakt}#contact aby uzyskać więcej +informacji. + +${projekt} używa Git jako systemu kontroli wersji i zarządzania kodem +źródłowym. Jak wyjaśniono w {repozytorium Git}#git-repositories są dwie +główne gałęzie rozwoju: *{debian}* i *{debian-next}*. Każdy może wprowadzić +zmiany do gałęzi *{debian-next}* w repozytoriach ive-boot, live-build, +live-config, live-images, live-manual i live-tools. + +Jednakże istnieją pewne restrykcje. Serwer odrzuci: + +_* Non fast-forward pushes. + +_* Zmiany wymagające scalenia. + +_* Dodawanie lub usuwanie tagów lub gałęzi rozwojowych. + +Nawet jeżeli wszystkie zmiany mogą być później zweryfikowane, prosimy abyś +używał zdrowego rozsądku i tworzył dobre zmiany opisane dobrym komentarzem. + +_* Pisz komentarze do zmian, które składają się z pełnych, sensownych zdań w +języku angielskim, począwszy od dużej litery, a kończących się +kropką. Zwykle te komentarze zaczynają się od +"Fixing/Adding/Removing/Correcting/Translating/...". +("Naprawianie/Dodawanie/Usuwanie/Korygowanie/Tłumaczenie/ itd. ... ".) + +_* Pisz dobre komenarze do zmian. Pierwsza linia musi być dokładne +podsumowanie treści popełnić, która zostanie uwzględniona w liście zmian +(ang. changelog). Jeśli musisz zrobić kilka wyjaśnień, napisz je niżej +pozostawiając pusty wiersz po pierwszej lini, a następnie kolejny pusty +wiersz po każdym akapicie. Linie każdego akapitu nie powinny przekraczać 80 +znaków. + +_ * Wysyłaj zmiany osobno. To znaczy; nie mieszaj niepowiązanych ze sobą +rzeczy w tej samej zmianie. Dodać osobną zmianę dla każdej rzeczy, którą +zmieniasz. + +2~ Wprowadzanie zmian + +W celu wysłania zmian do repozytoriów, należy wykonać następującą +procedurę. Tutaj używamy live-manual jako przykładu, więc zastąp go nazwą +repozytorium, z którym chcesz pracować. Aby uzyskać szczegółowe informacje +na temat edycji podręcznika live-manual zobacz: {Współtworzenie tego +dokumentu}#how-to-contribute. + +_* Pobierz publiczny klucz do wprowadzania zmian: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Dodaj następującą sekcję do twojej konfiguracji klienta openssh: + +code{ + +$ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Sprawdź i sklonuj kopię live-manual przez through ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Upewnij się, że masz ustawionego autora i adres email w konfiguracji Git: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Ważne:}* Pamiętaj, że powinno się wprowadzać wszelkie zmiany wyłącznie w gałęzi *{debian-next}*. + +_* Wprowadź zmiany. W tym przykładzie będzie najpierw napisać nowy dział +dotyczący stosowania plastrów, a następnie przygotować się do popełnienia +dodawanie plików i pisanie popełnienia wiadomość tak: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Wyślij poprawki na serwer: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/project_git.ssi new file mode 100644 index 0000000..075d6b6 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/project_git.ssi @@ -0,0 +1,88 @@ +:B~ Repozytorium Git + +1~git-repositories Repozytorium Git + +Lista wszystkich dostępnych repozytoriów dla ${project} można znaleźć na +stronie http://live-systems.org/gitweb/. Adres URL projektu git ma postać: +#{protocol://live-systems.org/git/repository}#. Tak więc, w celu sklonowania +live-manual, uruchom: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Lub + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Lub + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +Adres do sklonowania z uprawnieniami zapisu ma postać: +#{git@live-systems.org:/repository}#. + +A zatem jeszcze raz, aby sklonować live-manual po ssh wpisz: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +Drzewo git składa się z wielu różnych gałęzi. Gałęzie, które szczególnie +wymagają poświęcenia uwagi to *{debian}* i *{debian-next}*, ponieważ +zawierają one rzeczywistą pracy, które ostatecznie będzie znajdować się w +każdej nowej wersji. + +Po sklonowaniu każdego z istniejących repozytoriów, będziesz w gałęzi +*{debian}*. To jest właściwe, aby móc przyjrzeć się stanowi najnowszej +wersji projektu, ale przed rozpoczęciem pracy ważne jest, aby przejść do +gałęzi *{debian-next}*. Aby to zrobić: + +code{ + + $ git checkout debian-next + +}code + +Gałąź *{debian-next}*, która nie zawsze porusza się do przodu, gdzie +wszystkie zmiany są najpierw wprowadzane przed połączeniem w gałęzi +*{debian}*. Aby dokonać analogii, to jest jak poligon doświadczalny. Jeśli +pracujesz w tej branży i potrzebujesz wykonać polecenie pull (wyciągnąć), +będzie trzeba użyć #{git pull --rebase}#, tak aby lokalne modyfikacje +zostały zachowane przy wyciąganiu z serwera, a następnie Twoje zmiany +zostaną wprowadzone na szczycie wszystkich innych. + +2~ Obsługa wielu repozytoriów + +Jeśli masz zamiar sklonować kilka repozytoriów systemów live i chcesz +przejść do gałęzi *{debian-next}* od razu aby sprawdzić najnowszy kod, +napisać poprawkę lub przyczynić się z tłumaczeniem powinieneś wiedzieć, że +serwer git zapewnia #{mrconfig}#. Plik,który ułatwia obsługę wielu +repozytoriów. Aby z niego korzystać musisz zainstalować pakiet /{mr}/ a po +tym, uruchomić: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +Ta komenda automatycznie sklonuje i sprawdzi do gałęzi *{debian-next}* +repozytorium rozwojowego pakietów Debiana wytworzonych w ramach +projektu. Należą do nich, między innymi, repozytorium live-images, który +zawiera konfiguracje, używane do gotowych obrazów, które projekt publikuje +do ogólnego użytku. Aby uzyskać więcej informacji na temat korzystania z +tego repozytorium, zobacz {Klonowanie konfiguracji opublikowanej przez +Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/project_procedures.ssi new file mode 100644 index 0000000..836debd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/project_procedures.ssi @@ -0,0 +1,101 @@ +:B~ Procedury + +1~procedures Procedury + +Rozdział ten dokumentuje procedury dla ${project} dla różnych zadań, które +wymagają współpracy z innymi zespołami w Debianie. + +2~ Główne wydanie + +Wydawanie nowej stabilnej wersji głównej Debiana zawiera wiele różnych +zespołów pracujących razem, aby tak się stało. W pewnym momencie, na zespół +live dochodzi do pewnego momentu i buduje obrazy systemów live. Wymagania, +aby to zrobić to: + +_* Serwer lustrzany zawierający wydane wersje dla Debiana i archiwum +debian-bezpieczeństwa, które mogą uzyskać dostęp buildd debian-live. + +_* Nazwy obrazu muszą być znane (np. debian-live-WERSJA-ARCH-FLAVOUR.iso). + +_* Dane z debian-cd muszą zostać zsynchronizowane (listy wykluczające udeb). + +_* Obrazy są budowane i przechowywane na cdimage.debian.org. + +2~ Wydanie Docelowe + +_* Ponownie potrzebujemy zaktualizowanych serwerów lustrzanych Debiana i +debian-security. + +_* Obrazy są budowane i przechowywane na cdimage.debian.org. + +_* Wyślij wiadomość z obwieszczeniem. + +3~ Ostatnie Wydanie Docelowe Debiana + +Pamiętaj, aby dostosować zarówno chroot i serwery lustrzane z pakietami +binarnymi przy budowie ostatniego zestawu obrazów dla wydania Debiana po to +został przeniesione z ftp.debian.org do archive.debian.org. W ten sposób +stare prekompilowane obrazy live będą wciąż użyteczne bez modyfikacji +dokonanych przez użytkownika. + +3~ Szablon obwieszczenia dla wydania docelowego + + Email z obwieszczeniem dla wydania docelowego może być wygenerowany przy +użyciu poniższego szablonu i następującego polecenia: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + + Proszę dokładnie sprawdzić wiadomość przed wysłaniem i przekazać ją innym, +aby dokonali korekt. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [WPISZ TUTAJ SPECYFICZNĄ DLA LIVE ZMIANĘ] + * [WPISZ TUTAJ SPECYFICZNĄ DLA LIVE ZMIANĘ] + * [POWAŻNIEJSZE PROBLEMY MOGĄ WYMAGAĆ SWOJEJ OSOBNEJ SEKCJI] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_basics.ssi new file mode 100644 index 0000000..db6972e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_basics.ssi @@ -0,0 +1,626 @@ +:B~ Podstawy + +1~the-basics Podstawy + +This chapter contains a brief overview of the build process and instructions +for using the three most commonly used image types. The most versatile image +type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or +USB portable storage device. In certain special cases, as explained later, +the #{hdd}# type may be more suitable. The chapter includes detailed +instructions for building and using a #{netboot}# type image, which is a bit +more involved due to the setup required on the server. This is an slightly +advanced topic for anyone who is not already familiar with netbooting, but +it is included here because once the setup is done, it is a very convenient +way to test and deploy images for booting on the local network without the +hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting +which is, perhaps, the easiest way of using different images for different +purposes, switching from one to the other as needed using the internet as a +means. + +Throughout the chapter, we will often refer to the default filenames +produced by live-build. If you are {downloading a prebuilt +image}#downloading-prebuilt-images instead, the actual filenames may vary. + +2~what-is-live Co to jest system live? + +A live system usually means an operating system booted on a computer from a +removable medium, such as a CD-ROM or USB stick, or from a network, ready to +use without any installation on the usual drive(s), with auto-configuration +done at run time (see {Terms}#terms). + +With live systems, it's an operating system, built for one of the supported +architectures (currently amd64 and i386). It is made from the following +parts: + +_* *{Obraz jądra Linuxa}*, zazwyczaj nazwany #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux +boot, containing modules possibly needed to mount the System image and some +scripts to do it. + +_* *{System image}*: The operating system's filesystem image. Usually, a +SquashFS compressed filesystem is used to minimize the live system image +size. Note that it is read-only. So, during boot the live system will use a +RAM disk and 'union' mechanism to enable writing files within the running +system. However, all modifications will be lost upon shutdown unless +optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen +medium, possibly presenting a prompt or menu to allow selection of +options/configuration. It loads the Linux kernel and its initrd to run with +an associated system filesystem. Different solutions can be used, depending +on the target medium and format of the filesystem containing the previously +mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, +syslinux for HDD or USB drive booting from a VFAT partition, extlinux for +ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 +partitions, etc. + +You can use live-build to build the system image from your specifications, +set up a Linux kernel, its initrd, and a bootloader to run them, all in one +medium-dependant format (ISO9660 image, disk image, etc.). + +2~downloading-prebuilt-images Pobieranie prekompilowanych obrazów + +While the focus of this manual is developing and building your own live +images, you may simply wish to try one of our prebuilt images, either as an +introduction to their use or instead of building your own. These images are +built using our {live-images git repository}#clone-configuration-via-git and +official stable releases are published at +https://www.debian.org/CD/live/. In addition, older and upcoming releases, +and unofficial images containing non-free firmware and drivers are available +at http://live-systems.org/cdimage/release/. + +2~using-web-builder Using the web live image builder + +As a service to the community, we run a web-based live image builder service +at http://live-systems.org/build/. This site is maintained on a best effort +basis. That is, although we strive to keep it up-to-date and operational at +all times, and do issue notices for significant operational outages, we +cannot guarantee 100% availability or fast image building, and the service +may occasionally have issues that take some time to resolve. If you have +problems or questions about the service, please {contact us}#contact, +providing us with the link to your build. + +3~ Używanie i przestrogi dotyczące Web buildera + +The web interface currently makes no provision to prevent the use of invalid +combinations of options, and in particular, where changing an option would +normally (i.e. using live-build directly) change defaults of other options +listed in the web form, the web builder does not change these defaults. Most +notably, if you change #{--architectures}# from the default #{i386}# to +#{amd64}#, you must change the corresponding option #{--linux-flavours}# +from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for +the version of live-build installed on the web builder for more details. The +version number of live-build is listed at the bottom of the web builder +page. + +The time estimate given by the web builder is a crude estimate only and may +not reflect how long your build actually takes. Nor is the estimate updated +once it is displayed. Please be patient. Do not refresh the page you land on +after submitting the build, as this will resubmit a new build with the same +parameters. You should {contact us}#contact if you don't receive +notification of your build only once you are certain you've waited long +enough and verified the notification e-mail did not get caught by your own +e-mail spam filter. + +The web builder is limited in the kinds of images it can build. This keeps +it simple and efficient to use and maintain. If you would like to make +customizations that are not provided for by the web interface, the rest of +this manual explains how to build your own images using live-build. + +2~building-iso-hybrid Pierwsze kroki: budowanie obrazu ISO-hybrydy + +Regardless of the image type, you will need to perform the same basic steps +to build an image each time. As a first example, create a build directory, +change to that directory and then execute the following sequence of +live-build commands to create a basic ISO hybrid image containing a default +live system without X.org. It is suitable for burning to CD or DVD media, +and also to copy onto a USB stick. + +The name of the working directory is absolutely up to you, but if you take a +look at the examples used throughout live-manual, it is a good idea to use a +name that helps you identify the image you are working with in each +directory, especially if you are working or experimenting with different +image types. In this case you are going to build a default system so let's +call it, for example, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy +in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their +various options will be used. See {The lb config command}#lb-config for more +details. + +Now that the "config/" hierarchy exists, build the image with the #{lb +build}# command: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and +your network connection. When it is complete, there should be a +#{live-image-i386.hybrid.iso}# image file, ready to use, in the current +directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Korzystanie z hybrydowego obrazu ISO live + +After either building or downloading an ISO hybrid image, which can be +obtained at https://www.debian.org/CD/live/, the usual next step is to +prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or +a USB stick. + +3~burning-iso-image Wypalanie obrazu ISO na fizycznym nośniku + +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the +command-line to burn the image. For instance: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Kopiowanie obrazu ISO-hybrydy na nośnik USB + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick +with the #{cp}# program or an equivalent. Plug in a USB stick with a size +large enough for your image file and determine which device it is, which we +hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, +such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find +the right device name by looking in #{dmesg}#'s output after plugging in the +stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# +command to copy the image to the stick. *{This will definitely overwrite +any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Wykorzystanie przestrzeni pozostałej na nośniku USB + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first +partition on the device will be filled up by the live system. To use the +remaining free space, use a partitioning tool such as /{gparted}/ or +/{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +After the partition is created, where #{${PARTITION}}# is the name of the +partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One +possible choice would be ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-medium Uruchamianie nośnika live + +The first time you boot your live medium, whether CD, DVD, USB key, or PXE +boot, some setup in your computer's BIOS may be needed first. Since BIOSes +vary greatly in features and key bindings, we cannot get into the topic in +depth here. Some BIOSes provide a key to bring up a menu of boot devices at +boot time, which is the easiest way if it is available on your +system. Otherwise, you need to enter the BIOS configuration menu and change +the boot order to place the boot device for the live system before your +normal boot device. + +Once you've booted the medium, you are presented with a boot menu. If you +just press enter here, the system will boot using the default entry, +#{Live}# and default options. For more information about boot options, see +the "help" entry in the menu and also the live-boot and live-config man +pages found within the live system. + +Assuming you've selected #{Live}# and booted a default desktop live image, +after the boot messages scroll by, you should be automatically logged into +the #{user}# account and see a desktop, ready to use. If you have booted a +console-only image, such as a #{standard}# flavour {prebuilt +image}#downloading-prebuilt-images, you should be automatically logged in on +the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Używanie wirtualnej maszyny do testowania + +It can be a great time-saver for the development of live images to run them +in a virtual machine (VM). This is not without its caveats: + +_* Running a VM requires enough RAM for both the guest OS and the host and a +CPU with hardware support for virtualization is recommended. + +_* There are some inherent limitations to running on a VM, e.g. poor video +performance, limited choice of emulated hardware. + +_* When developing for specific hardware, there is no substitute for running +on the hardware itself. + +_* Occasionally there are bugs that relate only to running in a VM. When in +doubt, test your image directly on the hardware. + +Provided you can work within these constraints, survey the available VM +software and choose one that is suitable for your needs. + +3~testing-iso-with-qemu Testowanie obrazu ISO z użyciem QEMU + +The most versatile VM in Debian is QEMU. If your processor has hardware +support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ +package description briefly lists the requirements. + +First, install /{qemu-kvm}/ if your processor supports it. If not, install +/{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in +the following examples. The /{qemu-utils}/ package is also valuable for +creating virtual disk images with #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Uruchamianie obrazu ISO jest proste: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + + Zobacz podręczniki man, aby uzyskać więcej szczegółów. + +3~testing-iso-with-virtualbox Testowanie obrazu ISO z użyciem VirtualBox'a + +W celu przetestowania ISO w /{VirtualBox}/'ie: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use +#{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +In order to make the dkms package work, also the kernel headers for the +kernel flavour used in your image need to be installed. Instead of manually +listing the correct /{linux-headers}/ package in above created package list, +the selection of the right package can be done automatically by live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Budowanie i używanie obrazu HDD + +Building an HDD image is similar to an ISO hybrid one in all respects except +you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# +which cannot be burnt to optical media. It is suitable for booting from USB +sticks, USB hard drives, and various other portable storage +devices. Normally, an ISO hybrid image can be used for this purpose instead, +but if you have a BIOS which does not handle hybrid images properly, you +need an HDD image. + +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Run the #{lb config}# command as before, except this time specifying the HDD +image type: + +code{ + + $ lb config -b hdd + +}code + +A teraz zbuduj obraz używając polecenia #{lb build}#: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in +the current directory. + +The generated binary image contains a VFAT partition and the syslinux +bootloader, ready to be directly written on a USB device. Once again, using +an HDD image is just like using an ISO hybrid one on USB. Follow the +instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except +use the filename #{live-image-i386.img}# instead of +#{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described +above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run +#{kvm}# or #{qemu}#, depending on which version your host system needs, +specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Budowanie obrazu netboot + +The following sequence of commands will create a basic netboot image +containing a default live system without X.org. It is suitable for booting +over the network. + +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean +up the necessary stages. The cause for this is that in netboot setups, a +different initramfs configuration needs to be used which live-build performs +automatically when building netboot images. Since the initramfs creation +belongs to the chroot stage, switching to netboot in an existing build +directory means to rebuild the chroot stage too. Therefore, #{lb clean}# +(which will remove the chroot stage, too) needs to be used. + +Run the #{lb config}# command as follows to configure your image for +netbooting: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +In contrast with the ISO and HDD images, netbooting does not, itself, serve +the filesystem image to the client, so the files must be served via +NFS. Different network filesystems can be chosen through lb config. The +#{--net-root-path}# and #{--net-root-server}# options specify the location +and server, respectively, of the NFS server where the filesystem image will +be located at boot time. Make sure these are set to suitable values for your +network and server. + +A teraz zbuduj obraz używając polecenia #{lb build}#: + +code{ + + # lb build + +}code + +In a network boot, the client runs a small piece of software which usually +resides on the EPROM of the Ethernet card. This program sends a DHCP request +to get an IP address and information about what to do next. Typically, the +next step is getting a higher level bootloader via the TFTP protocol. That +could be pxelinux, GRUB, or even boot directly to an operating system like +Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# +archive in the #{/srv/debian-live}# directory, you'll find the filesystem +image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux +bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the +DHCP server, the TFTP server and the NFS server. + +3~ Serwer DHCP + +We must configure our network's DHCP server to be sure to give an IP address +to the netbooting client system, and to advertise the location of the PXE +bootloader. + +Here is an example for inspiration, written for the ISC DHCP server +#{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + +subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Serwer TFTP + +This serves the kernel and initial ramdisk to the system at run time. + +You should install the /{tftpd-hpa}/ package. It can serve all files +contained inside a root directory, usually #{/srv/tftp}#. To let it serve +files inside #{/srv/debian-live/tftpboot}#, run as root the following +command: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +and fill in the new tftp server directory when being asked about it. + +3~ Serwer NFS + +Once the guest computer has downloaded and booted a Linux kernel and loaded +its initrd, it will try to mount the Live filesystem image through a NFS +server. + +Musisz zainstalować pakiet /{nfs-kernel-server}/. + +Then, make the filesystem image available through NFS by adding a line like +the following to #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +and tell the NFS server about this new export with the following command: + +code{ + + # exportfs -rv + +}code + +Setting up these three services can be a little tricky. You might need some +patience to get all of them working together. For more information, see the +syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the +Debian Installer Manual's TFTP Net Booting section at +http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, +as their processes are very similar. + +3~ Netboot testing HowTo + +Netboot image creation is made easy with live-build, but testing the images +on physical machines can be really time consuming. + +Aby ułatwić sobie życie możemy użyć wirtualizacji. + +3~ Qemu + +_* Zainstaluj /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Edytuj #{/etc/qemu-ifup}#: + +code{ + +#!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Zainstaluj, lub zbuduj #{grub-floppy-netboot}#. + +Uruchom #{qemu}# z "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using +the internet as a means. The requirements for webbooting are very few. On +the one hand, you need a medium with a bootloader, an initial ramdisk and a +kernel. On the other hand, a web server to store the squashfs files which +contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which +are available on the project's homepage at http://live-systems.org/. Using +prebuilt images would be handy for doing initial testing until one can fine +tune their own needs. If you have built a live image you will find the files +needed for webbooting in the build directory under #{binary/live/}#. The +files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso +image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific +case, it would be #{/mnt/live/}#. This method has the disadvantage that you +need to be root to be able to mount the image. However, it has the advantage +that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image +and uploading it to the web server at the same time, is using the midnight +commander or /{mc}/. If you have the /{genisoimage}/ package installed, the +two-pane file manager allows you to browse the contents of an iso file in +one pane and upload the files via ftp in the other pane. Even though this +method requires manual work, it does not require root privileges. + +3~ Uruchamianie obrazów webboot + +While some users will prefer virtualization to test webbooting, we refer to +real hardware here to match the following possible use case which should +only be considered as an example. + +In order to boot a webboot image it is enough to have the components +mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a +directory named #{live/}# and install syslinux as bootloader. Then boot from +the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot +options. live-boot will retrieve the squashfs file and store it into +ram. This way, it is possible to use the downloaded compressed filesystem as +a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-binary.ssi new file mode 100644 index 0000000..81139ca --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-binary.ssi @@ -0,0 +1,64 @@ +:B~ Dostosowywanie obrazu binarnego + +1~customizing-binary Dostosowywanie obrazu binarnego + +2~ Programy ładujące (ang. Bootloadery) + +live-build używa /{syslinux}/ i niektórych jego pochodnych (w zależności od +typu obrazu) w domyślnym programie ładującym (ang. bootloader). Można je +łatwo dostosować do własnych potrzeb. + +W celu wykorzystania pełnego motywu, skopiuj +#{/usr/share/live/build/bootloaders}# do #{config/bootloaders}# i edytuj +tam te pliki. Jeśli nie chcesz się martwić modyfikacją wszystkich +obsługiwanych konfiguracji programu ładującego (ang. bootloader), tylko +zapewnienie lokalnego zmodyfikowaną kopię jednego z typu programów, np. * +{isolinux} * w # {config / programy ładujące / isolinux} # wystarczy też, w +zależności od przypadku użycia. + +Podczas modyfikacji jednego z domyślnych motywów, jeśli chcesz korzystać z +indywidualnego obrazu tła, który będzie wyświetlany razem z menu startowym, +dodaj obraz splash.png 640x480 pikseli. Następnie usuń plik splash.svg. + +Istnieje wiele możliwości, jeśli chodzi o wprowadzanie zmian. Na przykład, +pochodne syslinux mają domyślnie skonfigurowany limit czasowy (ang. timeout) +na 0 (zero), co oznacza, że wstrzymają się one na czas nieokreślony na w ich +ekranie powitalnym aż do naciśnięcia klawisza. + +Aby zmienić limit czasowy podczas rozruchu w domyślnym obrazie +#{iso-hybrid}# wystarczy zmienić domyślny plik *{isolinux.cfg}* określając +limit czasu (ang. timeout) w jednostkach 1/10 sekundy. Zmodyfikowany +*{isolinux.cfg}* uruchamiający rozruch po pięciu sekundach byłby podobny do +tego: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ Metadane ISO + +Podczas tworzenia binarnego obrazu ISO9660, można korzystać z następujących +opcji, aby dodać różne metadane tekstowe do obrazu. To może pomóc w +identyfikacji wersji lub konfiguracji obrazu bez uruchamiania go. + +_* #{LB_ISO_APPLICATION/--iso-application NAZWA}#: Pole to powinno opisywać +zastosowanie obrazu. Maksymalna długość tego pola wynosi 128 znaków. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: Pole to powinno opisywać +przygotowującego obraz, zwykle z kilkoma danymi kontaktowymi. Domyślną +wartością tej opcji jest używana wersja live-build, które może później pomóc +przy debugowaniu. Maksymalna długość tego pola wynosi 128 znaków. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: Pole to powinno opisywać +wydawcę obrazu, zwykle z kilkoma danymi kontaktowymi. Maksymalna długość +tego pola wynosi 128 znaków. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: Pole to powinno opisywać ID woluminu +obrazu. Jest używane jako etykieta widoczna dla użytkownika na niektórych +platformach, takich jak Windows i Apple Mac OS. Długość maksymalna dla tego +pola to 32 znaków. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-contents.ssi new file mode 100644 index 0000000..055599c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-contents.ssi @@ -0,0 +1,142 @@ +:B~ Dostosowywanie zawartości + +1~customizing-contents Dostosowywanie zawartości + +Ten rozdział omawia dokładną regulację dostosowywania zawartości systemu +poza samym wybieraniem pakietów do wyboru, które będą zawarte. Uwzględnianie +pozwala dodać lub wymienić dowolne pliki w obrazie systemu live, haki +pozwalają na wykonanie dowolnego polecenia na różnych etapach produkcji oraz +w czasie rozruchu a opcji preseeding pozwala skonfigurować pakiety, gdy są +zainstalowane poprzez dostarczenie odpowiedzi na pytania debconfa. + +2~includes Uwzględnianie + +Chociaż najlepiej byłoby gdyby system live zawierał się wyłącznie z plików +dostarczonych przez całkowicie niemodyfikowane pakiety, to czasami +wygodniejszym jest, dostarczenie lub zmodyfikowanie pewnych treści za pomocą +plików. Korzystając z uwzględniania, można dodać (lub wymienić) dowolne +pliki w systemie obrazu live. live-build dostarcza dwa takie mechanizmy +wykorzystania: + +_* Lokalne uwzględnianie chroot: Pozwoli Ci dodać lub zastąpić pliki w +systemie plików chroot/live. Zobacz {Lokalne uwzględnianie +chroot/live}#live-chroot-local-includes, aby uzyskać więcej informacji. + +_* Lokalne uwzględnianie danych binarnych: Pozwoli Ci dodać lub zastąpić +pliki w obrazie binarnym. Zobacz {Lokalnych uwzględnianie danych +binarnych}#binary-local-includes, aby uzyskać więcej informacji. + +Proszę zobaczyć {Definicje}#terms aby uzyskać więcej informacji na temat +różnicy między obrazami "binarnymi" a obrazami "live". + +3~live-chroot-local-includes Lokalnie uwzględniane w chroot/live + +Lokalnie uwzględnione w chroot mogą być używane, aby dodać lub zastąpić +pliki w systemie plików chroot/live, tak aby mogły być one użyte w systemie +live. Typowym zastosowaniem jest dostarczenie szkieletowego katalogu +użytkownika (#{/etc/skel}#) używanego przez system live do tworzenia +katalogu domowego użytkownika live. Innym jest dostarczanie plików +konfiguracyjnych, które mogą być po prostu dodane lub podmienione w obrazie +bez przetwarzania; zobacz {Lokalne haki +chroot/live}#live-chroot-local-hooks, czy potrzebne jest przetwarzanie. + +Aby dołączyć pliki, po prostu dodaj je do katalogu +#{config/includes.chroot}#. Ten katalog odnosi się do katalogu root #{/}# +systemu live. Na przykład, aby dodać plik #{/var/www/index.html}# do systemu +live, użyj: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Konfiguracja będzie mieć następujący układ: + +code{ + +- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Lokalnie uwzględnione w chroot są instalowane po instalacji pakietów, tak że +pliki zainstalowane przez pakiety są zastępowane. + +3~binary-local-includes Lokalnie uwzględniane dane binarne + +Aby zawierać materiały takie jak filmy lub dokumentacja na systemie plików +nośnika tak, aby były one dostępne od razu po włożeniu nośnika bez +uruchamiania systemu live, możesz użyć lokalnego uwzględniania danych +binarnych. Działa to w podobny sposób do lokalnego uwzględniania w +chroot/live. Załóżmy na przykład, że pliki #{~/video_demo.*}# to filmy +demonstacyjne systemu live opisanego przez i dowiązane przez stronę indeksu +HTML. Wystarczy skopiować materiał z #{config/includes.binary/}# w +następujący sposób: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +Pliki te pojawią się teraz w katalogu głównym nośnika live. + +2~hooks Haki + +Haki pozwalają poleceniom aby były wykonywane w etapach chroot i binarnym +kompilacji w celu dostosowania obrazu. + +3~live-chroot-local-hooks Lokalne haki chroot/live + +Aby uruchomić komendy na etapie chroot, należy utworzyć skrypt hak z +przyrostkiem #{.hook.chroot}# zawierającym polecenia w katalogu +#{config/hooks/}#. Hak będzie działać w chroot po resztę konfiguracji chroot +zastosowano, więc pamiętaj, aby zapewnić, że konfiguracja zawiera wszystkie +pakiety i pliki do Twoich potrzeb haka w celu uruchomienia. Zobacz +przykładowe skrypty hak chroot dla różnych zadań dostosowywania wspólnej +chroot przewidzianych w # {/ usr / share / doc / live-build / przykłady / +haki} #, który można skopiować lub linku do korzystania z nich w swoim +własnym konfiguracji. + +3~boot-time-hooks Haki podczas uruchamiania + +Aby wykonać polecenia przy starcie systemu, możesz dostarczyć haki +live-config, jak wyjaśniono w jego podręczniku man w sekcji "Customization" +(ang. dostosowywanie). Przeanalizuj własne haki live-config dostarczone w +#{/lib/live/config/}#, zwracając uwagę na numery sekwencji. Następnie dodaj +swój własne hak z odpowiednim prefiksem numeru sekwencji, albo jako lokalnie +uwzględnione w chroot w #{config/includes.chroot/lib/live/config/}#, lub w +postaci niestandardowego pakietu omówione w {Instalowanie zmodyfikowanych +pakietów lub pakietów innych +firm}#installing-modified-or-third-party-packages. + +3~ Lokalne haki binarne + +Aby uruchomić komendy na etapie binarnym, należy utworzyć skrypt hak z +przyrostkiem #{.hook.binary}# zawierającym polecenia w katalogu +#{config/hooks/}#. Hak będzie uruchomiony po wszystkich innych binarnych +poleceniach, ale przed binary_checksums; ostatnim poleceniem. Polecenia haka +nie działają w środowisku chroot, więc należy zadbać, aby nie modyfikować +żadnych plików poza drzewem kompilacji albo może to uszkodzić system +kompilacji! Zobacz przykładowe skrypty binarne dla różnych typowych +binarnych zadań dostosowywania przewidzianych w +#{/usr/share/doc/live-build/examples/hooks}#, które można skopiować lub +utworzyć dowiązanie symboliczne aby skorzystać z nich w swojej własnej +konfiguracji. + +2~ Wstępne ustawienie pytań Debconfa (Preseeding) + +Pliki w katalogu #{config/preseed/}# z rozszerzeniem #{.cfg}# w następującym +etapie (#{.chroot}# lub #{.binary}#) są brane pod uwagę jako pliki preseed +debconfa i są instalowane za pomocą live-build przez +#{debconf-set-selections}# podczas odpowiedniego etapu. + +Aby uzyskać więcej informacji o debconf, proszę przeczytaj #{debconf(7)}# z +pakietu /{debconf}/. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-installer.ssi new file mode 100644 index 0000000..256bb6e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-installer.ssi @@ -0,0 +1,90 @@ +:B~ Dostosowywanie Instalatora Debiana + +1~customizing-installer Dostosowywanie Instalatora Debiana + +Obrazy systemów live mogą być zintegrowane z Instalatorem Debiana. Istnieje +wiele różnych typów instalacji, różniących się tym, co jest załączone w +obrazie i jak działa instalator. + +Proszę zwrócić uwagę na uważne wykorzystanie wielkich liter, podczas +odnoszenia się do "Debian Installer" (ang. Instalatora Debiana) w tej sekcji +- kiedy jest stosowany tak, że odnosi się wyraźnie do oficjalnego +instalatora dla systemu Debian, a nie cokolwiek innego, to jest często +postrzegana w skrócie jako "d-i". + +2~ Typy Instalatora Debiana + +Trzy główne rodzaje instalatora to: + +*{Instalator Debiana "Normal"}*: To jest normalny obraz systemu live z oddzielnym jądrem i initrd, który (gdy wybrany z odpowiedniego menu programu ładującego) uruchamia do standardowej instancji Instalatora Debiana, tak jakby pobrano obraz płyty Debiana i uruchomiło się go. Obrazy zawierające system typu live i inny niezależny instalator są często określane jako "połączone obrazy" (ang. combined images). + +Na takich obrazach, Debian jest instalowany przez pobieranie i instalowanie +pakietów .deb za pomocą /{debootstrap}/, z lokalnych mediów lub jakiegoś +opartego na sieci, w wyniku czego domyślny systemu Debian jest instalowany +na dysku twardym. + +Cały proces może być zapisany w pliku preseed i dostosowany na wiele różnych +sposób, przeczytaj odpowiednie strony w instrukcji Instalatora Debiana, aby +uzyskać więcej informacji. Kiedy utworzysz działający plik preseed, +live-build może automatycznie umieścić go w Twoim obrazie i włączyć go dla +Ciebie. + +*{Instalator Debiana "Live"}*: To jest obraz systemu live z oddzielnym jądrem i initrd, który (gdy wybrany z odpowiedniego menu programu ładującego) uruchamia do instancji Instalatora Debiana. + +Instalacja będzie przebiegać w identyczny sposób do instalacji "normalnej" +opisanej powyżej, ale na tym samym etapie instalacji, zamiast używać +/{debootstrap}/ aby pobrać i zainstalować pakiety, systemu plików obrazu +live zostanie skopiowany do celu. Jest to możliwe dzięki specjalnym pakiecie +udeb zwanym live-installer. + +Po tym etapie, Instalator Debiana kontynuuje normalnie, instalując i +konfigurując elementy, takie jak programy ładujące i lokalnych użytkowników, +itp. + +*{Uwaga:}* aby zapewnić wsparcie dla wpisów zarówno normalnych i instalatora live w bootloaderze (ang. programie ładującym) na tym samym nośniku live, należy wyłączyć instalatora live przez wpis w pliku preseed #{live-installer/enable=false}#. + +*{Instalator Debiana "Desktop"}*: Niezależnie od wybranego rodzaju Instalatora Debiana, #{di}# może zostać uruchomiony z pulpitu, klikając na jego ikonę. Jest bardziej przyjazny użytkownikowi w niektórych sytuacjach. W celu skorzystania z tej opcji, pakiet debian-installer-launcher musi zostać uwzględniony. + +Należy pamiętać, że domyślnie, live-build nie obejmuje obrazów Instalatora +Debiana w obrazach, musi to być sprecyzowane przez #{lb config}#. Również +należy również pamiętać, że aby działał "Desktop Installer" (ang. instalator +uruchamiany z poziomu pulpitu) to jądro systemu live musi być zgodne z +jądrem wykorzystywanym przez #{d-i}# dla określonej architektury. Na +przykład: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Dostosowywanie Instalatora Debiana przez preseeding + +Jak opisano w Podręczniku Instalatora Debiana, Załącznik B na +https://www.debian.org/releases/stable/i386/apb.html, "Plik preseed +dostarcza sposób, aby ustawić odpowiedzi na pytania zadawane w trakcie +procesu instalacji, bez konieczności ręcznego wprowadzania odpowiedzi, +podczas instalacji. Pozwala to w pełni zautomatyzować większość rodzajów +instalacji, a nawet oferuje kilka funkcji niedostępnych w zwykłych +instalacjach." Takie dostosowanie jest najlepiej osiągane używając +live-build poprzez umieszczenie konfiguracji w pliku #{preseed.cfg}# +zawartym w #{config/includes.installer/}#. Na przykład, aby ustawić +lokalizację na #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Dostosowywanie zawartości Instalatora Debiana + +Do celów doświadczalnych lub debugowania, możesz zechcieć dołączyć lokalnie +zbudowany element #{di}# w paczce udeb. Należy umieścić je w +#{config/packages.binary/}#, aby włączyć je do obrazu. Również dodatkowe lub +zamienne pliki i katalogi mogą być zawarte w initrd instalatora, w sposób +podobny do {Uwzględnianie lokalne live/chroot}#live-chroot-local-includes, +poprzez umieszczenie materiałów w #{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-overview.ssi new file mode 100644 index 0000000..6950059 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-overview.ssi @@ -0,0 +1,79 @@ +:B~ Dostosowywanie zawartości + +1~customization-overview Opis dostosowywania + +Ten rozdział zawiera przegląd różnych sposobów, w jaki można dostosować +system live. + +2~ Konfiguracja podczas kompilacji vs. podczas uruchamiania systemu + +Opcje konfiguracji systemu live są podzielone na opcje w czasie budowania, +które są stosowane w czasie kompilacji i na opcje w czasie rozruchu, które +są stosowane podczas uruchamiania systemu. Opcje podczas uruchamiania są +podzielone na te występujące wcześnie podczas uruchamiania, zastosowane +przez live-boot, i na te, występujące później, zastosowane przez +live-config. Każdy parametr rozruchu może zostać zmodyfikowany przez +użytkownika poprzez ustalenie go podczas startu. Obraz może być również +zbudowany z domyślnymi parametrami startowymi, dzięki czemu użytkownicy mogą +normalnie tylko uruchomić bezpośrednio systemu live bez podawania żadnych +parametrów, gdy wszystkie opcje domyślne są odpowiednie. W szczególności +argument #{lb --bootappend-live}# składa się z wszelkich opcji wiersza +poleceń domyślnych dla jądra systemu live, takich jak trwałość +(ang. persistence), układ klawiatury, lub strefa czasowa. Zobacz +{Dostosowywanie lokalizacji i języka}#customizing-locale-and-language, dla +przykładów. + +Opcje konfiguracyjne w czasie budowania są opisane w podręczniku man na +stronie #{lb config}#. Opcje konfiguracyjne w czasie rozruchu opisane są w +podręczniku man na stronach live-boot i live-config. Chociaż pakiety +startowe live-boot i live-config są zainstalowane w systemie live, który +budujesz, zaleca się również zainstalować je w systemie budowania dla +łatwego odniesienia podczas Twojej pracy przy konfiguracji. Jest to +bezpieczne, ponieważ żaden z zawartych w nich skryptów nie będzie +wykonywany, chyba że system zostanie skonfigurowany jako system live. + +2~stages-of-the-build Etapy kompilacji + +Proces kompilacji jest podzielony na etapy, w każdym z nich z zastosowanymi +w kolejności różnymi dostosowaniami. Pierwszym etapem do uruchomienia jest +etap *{bootstrap}*. Jest to wstępna faza wypełniania katalogu chroot +pakietami aby stworzyć kadłub systemu Debian. Następnym etapem jest +*{chroot}*, który kończy budowę katalogu chroot, wypełniania go wszystkimi +pakietami wymienionymi w konfiguracji, wraz z innymi materiałami. Najwęcej +dostosowywania zawartości odbywa się w tym etapie. Ostatnim etapem +przygotowania obrazu live jest etap *{binarny}* (ang. binary), który tworzy +możliwy do uruchomienia obraz, używając zawartości katalogu chroot do budowy +głównego systemu plików w systemie live, a tym instalatora i wszelkich +innych dodatkowych materiałów na nośniku docelowym poza system plików na +systemu live. Po skompilowaniu obrazu live, jeśli włączono, archiwum +źródłowe tarball jest budowane podczas etapu *{source}* (ang. źródło). + +W każdym z tych etapów istnieje szczególna sekwencja, w której stosuje się +polecenia. Są one usytuowane w taki sposób, aby zapewnić modyfikacjom bycie +ułożonym w rozsądny sposób. Na przykład, w etapie *{chroot}*, +prekonfiguracja (ang. preseeding) jest stosowana, zanim zostaną +zainstalowane jakiekolwiek pakiety, pakiety są instalowane zanim +jakiekolwiek lokalnie zawarte pliki zostaną kopiowane, a haki są wprowadzane +później, gdy wszystkie materiały są już na miejscu. + +2~ Uzupełnienie lb config plikami + +Mimo, że #{lb config}# tworzy konfigurację katalogów w #{config/}#, aby +osiągnąć swoje cele, może być konieczne udostępnienie dodatkowych plików w +podkatalogach #{config/}#. W zależności od tego, gdzie pliki są +przechowywane w konfiguracji, mogą być skopiowane do systemu plików systemu +live lub do binarnego obrazu systemu plików, lub mogą zostać zapewnione +konfiguracje w czasie budowy systemu, które byłoby kłopotliwie do +przekazania jako opcje wiersza polecenia. Można zawrzeć rzeczy takie jak +niestandardowe listy pakietów, niestandardowa grafika lub inny skrypt do +uruchomienia zarówno w czasie kompilacji jak i w czasie startu systemu, +zwiększając już znaczną elastyczność debian-live swoim własnych kodem. + +2~ Zadania dostosowywania + +Kolejne rozdziały są podzielone na rodzaje zadań dostosowywania, który +użytkownicy zazwyczaj wykonują: {Dostosowywanie instalacji +pakietu}#customizing-package-installation, {Dostosowywanie +zawartości}#customizing-contents i {Dostosowywanie ustawień regionalnych i +języka}#customizing-locale-and-language obejmują tylko niektóre z rzeczy, +które możesz zrobić. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-packages.ssi new file mode 100644 index 0000000..d8d8ce5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-packages.ssi @@ -0,0 +1,644 @@ +:B~ Dostosowywanie instalacji pakietów + +1~customizing-package-installation Dostosowywanie instalacji pakietów + +Perhaps the most basic customization of a live system is the selection of +packages to be included in the image. This chapter guides you through the +various build-time options to customize live-build's installation of +packages. The broadest choices influencing which packages are available to +install in the image are the distribution and archive areas. To ensure +decent download speeds, you should choose a nearby distribution mirror. You +can also add your own repositories for backports, experimental or custom +packages, or include packages directly as files. You can define lists of +packages, including metapackages which will install many related packages at +once, such as packages for a particular desktop or language. Finally, a +number of options give some control over /{apt}/, or if you prefer, +/{aptitude}/, at build time when packages are installed. You may find these +handy if you use a proxy, want to disable installation of recommended +packages to save space, or need to control which versions of packages are +installed via APT pinning, to name a few possibilities. + +2~ Źródła pakietu + +3~ Dystrybucja, działy archiwum i tryb + +The distribution you choose has the broadest impact on which packages are +available to include in your live image. Specify the codename, which +defaults to ${testing} for the ${testing} version of live-build. Any current +distribution carried in the archive may be specified by its codename +here. (See {Terms}#terms for more details.) The #{--distribution}# option +not only influences the source of packages within the archive, but also +instructs live-build to behave as needed to build each supported +distribution. For example, to build against the *{unstable}* release, sid, +specify: + +code{ + + $ lb config --distribution sid + +}code + +Within the distribution archive, archive areas are major divisions of the +archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only +#{main}# contains software that is part of the Debian distribution, hence +that is the default. One or more values may be specified, e.g. + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimental support is available for some Debian derivatives through a +#{--mode}# option. By default, this option is set to #{debian}# only if you +are building on a Debian or on an unknown system. If #{lb config}# is +invoked on any of the supported derivatives, it will default to create an +image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, +the distribution names and archive areas for the specified derivative are +supported instead of the ones for Debian. The mode also modifies live-build +behaviour to suit the derivatives. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Serwery lustrzane dystrybucji + +The Debian archive is replicated across a large network of mirrors around +the world so that people in each region can choose a nearby mirror for best +download speed. Each of the #{--mirror-*}# options governs which +distribution mirror is used at various stages of the build. Recall from +{Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is +when the chroot is initially populated by /{debootstrap}/ with a minimal +system, and the *{chroot}* stage is when the chroot used to construct the +live system's filesystem is built. Thus, the corresponding mirror switches +are used for those stages, and later, in the *{binary}* stage, the +#{--mirror-binary}# and #{--mirror-binary-security}# values are used, +superseding any mirrors used in an earlier stage. + +3~distribution-mirrors-build-time Serwery lustrzane dystrybucji używane +podczas budowania obrazu + +To set the distribution mirrors used at build time to point at a local +mirror, it is sufficient to set #{--mirror-bootstrap}# and +#{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +Serwer lustrzany chroot, określony przez #{--mirror-chroot}#, domyślnie do +wartości #{--mirror-bootstrap}#. + +3~ Serwery lustrzane dystrybucji użyte podczas uruchomienia + +The #{--mirror-binary*}# options govern the distribution mirrors placed in +the binary image. These may be used to install additional packages while +running the live system. The defaults employ #{httpredir.debian.org}#, a +service that chooses a geographically close mirror based, among other +things, on the user's IP family and the availability of the mirrors. This is +a suitable choice when you cannot predict which mirror will be best for all +of your users. Or you may specify your own values as shown in the example +below. An image built from this configuration would only be suitable for +users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Dodatkowe repozytoria + +You may add more repositories, broadening your package choices beyond what +is available in your target distribution. These may be, for example, for +backports, experimental or custom packages. To configure additional +repositories, create #{config/archives/your-repository.list.chroot}#, and/or +#{config/archives/your-repository.list.binary}# files. As with the +#{--mirror-*}# options, these govern the repositories used in the *{chroot}* +stage when building the image, and in the *{binary}* stage, i.e. for use +when running the live system. + +For example, #{config/archives/live.list.chroot}# allows you to install +packages from the debian-live snapshot repository at live system build time. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +If you add the same line to #{config/archives/live.list.binary}#, the +repository will be added to your live system's #{/etc/apt/sources.list.d/}# +directory. + +Jeżeli takie pliki istnieją to zostaną wybrane automatycznie. + +Należy również umieścić klucz GPG używany do podpisywania repozytorium w +#{config/archives/twój-klucz-repozytorium.key{binary,chroot}}#. + +Should you need custom APT pinning, such APT preferences snippets can be +placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and +will be automatically added to your live system's +#{/etc/apt/preferences.d/}# directory. + +2~choosing-packages-to-install Wybieranie pakietów do instalacji + +There are a number of ways to choose which packages live-build will install +in your image, covering a variety of different needs. You can simply name +individual packages to install in a package list. You can also use +metapackages in those lists, or select them using package control file +fields. And finally, you may place package files in your #{config/}# tree, +which is well suited to testing of new or experimental packages before they +are available from a repository. + +3~package-lists Lista pakietów + +Listy pakietów są skutecznym sposobem wyrażenia, które pakiety powinny +zostać zainstalowane.Składnia list obsługuje instrukcje warunkowe, które +ułatwiają budowanie list i dostosowywanie ich do wykorzystania w wielu +konfiguracjach. Nazwy pakietów mogą być także wstrzykiwane do listy za +pomocą pomocników powłoki w czasie kompilacji. + +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. + +3~using-metapackages Używanie metapakietów + +Najprostszym sposobem, aby wypełnić swoją listę pakietów jest użycie +metapakietu zadań dostarczanych przez dystrybucję. Na przykład: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# +2.x. Unlike predefined lists, task metapackages are not specific to the Live +System project. Instead, they are maintained by specialist working groups +within the distribution and therefore reflect the consensus of each group +about which packages best serve the needs of the intended users. They also +cover a much broader range of use cases than the predefined lists they +replace. + +All task metapackages are prefixed #{task-}#, so a quick way to determine +which are available (though it may contain a handful of false hits that +match the name but aren't metapackages) is to match on the package name +with: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +Oprócz tych, znajdziesz jeszcze inne metapakiety do różnych celów. Niektóre +są podzbiorami szerszych pakietów zadań, jak #{gnome-core}#, podczas gdy +inne są indywidualne specjalistyczne części czystego Debiana mieszanki, +takie jak metapakiety #{education-*}#. Aby wyświetlić wszystkie metapakiety +w archiwum, należy zainstalować pakiet #{debtags}# i wyświetlić wszystkie +pakiety z tagiem #{role::metapackage}# w następujący sposób: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Lokalna lista pakietów + +Whether you list metapackages, individual packages, or a combination of +both, all local package lists are stored in #{config/package-lists/}#. Since +more than one list can be used, this lends itself well to modular +designs. For example, you may decide to devote one list to a particular +choice of desktop, another to a collection of related packages that might as +easily be used on top of a different desktop. This allows you to experiment +with different combinations of sets of packages with a minimum of fuss, +sharing common lists between different live image projects. + +Package lists that exist in this directory need to have a #{.list}# suffix +in order to be processed, and then an additional stage suffix, #{.chroot}# +or #{.binary}# to indicate which stage the list is for. + +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. + +3~ Lokalna lista pakietów binarnych + +To make a binary stage list, place a file suffixed with #{.list.binary}# in +#{config/package-lists/}#. These packages are not installed in the live +filesystem, but are included on the live medium under #{pool/}#. You would +typically use such a list with one of the non-live installer variants. As +mentioned above, if you want this list to be the same as your chroot stage +list, simply use the #{.list}# suffix by itself. + +3~generated-package-lists Wygenerowana lista pakietów + +It sometimes happens that the best way to compose a list is to generate it +with a script. Any line starting with an exclamation point indicates a +command to be executed within the chroot when the image is built. For +example, one might include the line #{! grep-aptavail -n -sPackage +-FPriority standard | sort}# in a package list to produce a sorted list of +available packages with #{Priority: standard}#. + +In fact, selecting packages with the #{grep-aptavail}# command (from the +#{dctrl-tools}# package) is so useful that #{live-build}# provides a +#{Packages}# helper script as a convenience. This script takes two +arguments: #{field}# and #{pattern}#. Thus, you can create a list with the +following contents: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Używanie instrukcji warunkowych w listach pakietów. + +Any of the live-build configuration variables stored in #{config/*}# (minus +the #{LB_}# prefix) may be used in conditional statements in package +lists. Generally, this means any #{lb config}# option uppercased and with +dashes changed to underscores. But in practice, it is only the ones that +influence package selection that make sense, such as #{DISTRIBUTION}#, +#{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. + +Na przykład, aby zainstalować #{ia32-libs}# jeżeli wybrano #{--architectures +amd64}#: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +Można przetestować dowolny szereg wartości, na przykład zainstalować +/{memtest86+}/, jeżeli ustalono #{--architectures i386}# lub +#{--architectures amd64}#: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +You may also test against variables that may contain more than one value, +e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified +via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +Zagnieżdżanie instrukcji warunkowych jest nie obsługiwane. + +% FIXME: + +3~ Usuwanie pakietu podczas instalacji + +You can list packages in files with #{.list.chroot_live}# and +#{.list.chroot_install}# suffixes inside the #{config/package-lists}# +directory. If both a live and an install list exist, the packages in the +#{.list.chroot_live}# list are removed with a hook after the installation +(if the user uses the installer). The packages in the +#{.list.chroot_install}# list are present both in the live system and in the +installed system. This is a special tweak for the installer and may be +useful if you have #{--debian-installer live}# set in your config, and wish +to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Pulpit i zadania językowe + +Desktop and language tasks are special cases that need some extra planning +and configuration. Live images are different from Debian Installer images in +this respect. In the Debian Installer, if the medium was prepared for a +particular desktop environment flavour, the corresponding task will be +automatically installed. Thus, there are internal #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which +are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for +tasks for languages, but the user's language choice during the install +influences the selection of corresponding language tasks. + +When developing a desktop live image, the image typically boots directly to +a working desktop, the choices of both desktop and default language having +been made at build time, not at run time as in the case of the Debian +Installer. That's not to say that a live image couldn't be built to support +multiple desktops or multiple languages and offer the user a choice, but +that is not live-build's default behaviour. + +Because there is no provision made automatically for language tasks, which +include such things as language-specific fonts and input-method packages, if +you want them, you need to specify them in your configuration. For example, +a GNOME desktop image containing support for German might include these task +metapackages: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Rodzaj jądra i wersja + +One or more kernel flavours will be included in your image by default, +depending on the architecture. You can choose different flavours via the +#{--linux-flavours}# option. Each flavour is suffixed to the default stub +#{linux-image}# to form each metapackage name which in turn depends on an +exact kernel package to be included in your image. + +Thus by default, an #{amd64}# architecture image will include the +#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture +image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured +archives, you can specify a different kernel package name stub with the +#{--linux-packages}# option. For example, supposing you are building an +#{amd64}# architecture image and add the experimental archive for testing +purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# +kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Niestandardowe jądra + +You can build and include your own custom kernels, so long as they are +integrated within the Debian package management system. The live-build +system does not support kernels not built as #{.deb}# packages. + +The proper and recommended way to deploy your own kernel packages is to +follow the instructions in the #{kernel-handbook}#. Remember to modify the +ABI and flavour suffixes appropriately, then include a complete build of the +#{linux}# and matching #{linux-latest}# packages in your repository. + +If you opt to build the kernel packages without the matching metapackages, +you need to specify an appropriate #{--linux-packages}# stub as discussed in +{Kernel flavour and version}#kernel-flavour-and-version. As we explain in +{Installing modified or third-party +packages}#installing-modified-or-third-party-packages, it is best if you +include your custom kernel packages in your own repository, though the +alternatives discussed in that section work as well. + +It is beyond the scope of this document to give advice on how to customize +your kernel. However, you must at least ensure your configuration satisfies +these minimum requirements: + +_* Użyj startowego dysku RAM. + +_* Include the union filesystem module (i.e. usually #{aufs}#). + +_* Include any other filesystem modules required by your configuration +(i.e. usually #{squashfs}#). + +2~installing-modified-or-third-party-packages Instalowanie zmodyfikowanych +pakietów lub pakietów innych firm + +While it is against the philosophy of a live system, it may sometimes be +necessary to build a live system with modified versions of packages that are +in the Debian repository. This may be to modify or support additional +features, languages and branding, or even to remove elements of existing +packages that are undesirable. Similarly, "third-party" packages may be used +to add bespoke and/or proprietary functionality. + +This section does not cover advice regarding building or maintaining +modified packages. Joachim Breitner's 'How to fork privately' method from +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +may be of interest, however. The creation of bespoke packages is covered in +the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ +and elsewhere. + +Istnieją dwa sposoby instalacji niestandardowych pakietów: + +_* #{packages.chroot}# + +_* Używanie niestandardowego repozytorium APT + +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" +customizations but has a number of drawbacks, while using a custom APT +repository is more time-consuming to set up. + +3~ Używanie #{packages.chroot}#do instalacji niestandardowych pakietów + +To install a custom package, simply copy it to the +#{config/packages.chroot/}# directory. Packages that are inside this +directory will be automatically installed into the live system during build +- you do not need to specify them elsewhere. + +Packages *{must}* be named in the prescribed way. One simple way to do this +is to use #{dpkg-name}#. + +Korzystanie z #{packages.chroot}# do instalacji niestandardowych pakietów ma +wady: + +_* Nie jest możliwe użycie bezpiecznego APT. + +_* You must install all appropriate packages in the +#{config/packages.chroot/}# directory. + +_* It does not lend itself to storing live system configurations in revision +control. + +3~ Używanie repozytoriium APT aby zainstalować niestandarkowe pakiety + +Unlike using #{packages.chroot}#, when using a custom APT repository you +must ensure that you specify the packages elsewhere. See {Choosing packages +to install}#choosing-packages-to-install for details. + +While it may seem unnecessary effort to create an APT repository to install +custom packages, the infrastructure can be easily re-used at a later date to +offer updates of the modified packages. + +3~ Niestandardowe pakiety i APT + +live-build uses APT to install all packages into the live system so will +therefore inherit behaviours from this program. One relevant example is that +(assuming a default configuration) given a package available in two +different repositories with different version numbers, APT will elect to +install the package with the higher version number. + +Because of this, you may wish to increment the version number in your custom +packages' #{debian/changelog}# files to ensure that your modified version is +installed over one in the official Debian repositories. This may also be +achieved by altering the live system's APT pinning preferences - see {APT +pinning}#apt-pinning for more information. + +2~ Konfigurowanie APT podczas kompilacji + +You can configure APT through a number of options applied only at build +time. (APT configuration used in the running live system may be configured +in the normal way for live system contents, that is, by including the +appropriate configurations through #{config/includes.chroot/}#.) For a +complete list, look for options starting with #{apt}# in the #{lb_config}# +man page. + +3~choosing-apt-or-aptitude Wybieranie apt lub aptitude + +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages +at build time. Which utility is used is governed by the #{--apt}# argument +to #{lb config}#. Choose the method implementing the preferred behaviour for +package installation, the notable difference being how missing packages are +handled. + +_* #{apt}#: Używając tej metody, jeśli zaznaczono brakujący pakiet, +instalacja pakietu zakończy się niepowodzeniem. To jest domyślne ustawienie. + +_* #{aptitude}#: Używając tej metody, jeśli zaznaczono brakujący pakiet, +instalacja pakietu zakończy się powodzeniem. + +3~ Używanie serwera proxy z APT + +One commonly required APT configuration is to deal with building an image +behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# +or #{--apt-http-proxy}# options as needed, e.g. + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Podkręcanie APT celu zaoszczędzenia miejsca + +You may find yourself needing to save some space on the image medium, in +which case one or the other or both of the following options may be of +interest. + +Jeśli nie chcesz zawierać indeksów APT w obrazie, można je pominąć z: + +code{ + + $ lb config --apt-indices false + +}code + +This will not influence the entries in #{/etc/apt/sources.list}#, but merely +whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is +that APT needs those indices in order to operate in the live system, so +before performing #{apt-cache search}# or #{apt-get install}#, for instance, +the user must #{apt-get update}# first to create those indices. + +If you find the installation of recommended packages bloats your image too +much, provided you are prepared to deal with the consequences discussed +below, you may disable that default option of APT with: + +code{ + + $ lb config --apt-recommends false + +}code + +The most important consequence of turning off recommends is that +#{live-boot}# and #{live-config}# themselves recommend some packages that +provide important functionality used by most Live configurations, such as +#{user-setup}# which #{live-config}# recommends and is used to create the +live user. In all but the most exceptional circumstances you need to add +back at least some of these recommends to your package lists or else your +image will not work as expected, if at all. Look at the recommended packages +for each of the #{live-*}# packages included in your build and if you are +not certain you can omit them, add them back into your package lists. + +The more general consequence is that if you don't install recommended +packages for any given package, that is, "packages that would be found +together with this one in all but unusual installations" (Debian Policy +Manual, section 7.2), some packages that users of your Live system actually +need may be omitted. Therefore, we suggest you review the difference turning +off recommends makes to your packages list (see the #{binary.packages}# file +generated by #{lb build}#) and re-include in your list any missing packages +that you still want installed. Alternatively, if you find you only want a +small number of recommended packages left out, leave recommends enabled and +set a negative APT pin priority on selected packages to prevent them from +being installed, as explained in {APT pinning}#apt-pinning. + +3~ Przekazywanie opcji do apt lub aptitude + +If there is not a #{lb config}# option to alter APT's behaviour in the way +you need, use #{--apt-options}# or #{--aptitude-options}# to pass any +options through to your configured APT tool. See the man pages for #{apt}# +and #{aptitude}# for details. Note that both options have default values +that you will need to retain in addition to any overrides you may +provide. So, for example, suppose you have included something from +#{snapshot.debian.org}# for testing purposes and want to specify +#{Acquire::Check-Valid-Until=false}# to make APT happy with the stale +#{Release}# file, you would do so as per the following example, appending +the new option after the default value #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Please check the man pages to fully understand these options and when to use +them. This is an example only and should not be construed as advice to +configure your image this way. This option would not be appropriate for, +say, a final release of a live image. + +For more complicated APT configurations involving #{apt.conf}# options you +might want to create a #{config/apt/apt.conf}# file instead. See also the +other #{apt-*}# options for a few convenient shortcuts for frequently needed +options. + +3~apt-pinning Pinning APT + +For background, please first read the #{apt_preferences(5)}# man page. APT +pinning can be configured either for build time, or else for run time. For +the former, create #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the +latter, create #{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live +packages that end up in the binary image to be installed from sid at build +time. You need to add sid to your APT sources and pin the live packages from +it higher, but all other packages from it lower, than the default +priority. Thus, only the packages you want are installed from sid at build +time and all others are taken from the target system distribution, +${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Negative pin priorities will prevent a package from being installed, as in +the case where you do not want a package that is recommended by another +package. Suppose you are building an LXDE image using #{task-lxde-desktop}# +in #{config/package-lists/desktop.list.chroot}#, but don't want the user +prompted to store wifi passwords in the keyring. This metapackage depends on +/{lxde-core}/, which recommends /{gksu}/, which in turn recommends +/{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ +package. This can be done by adding the following stanza to +#{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-runtime.ssi new file mode 100644 index 0000000..1ccda5c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_customization-runtime.ssi @@ -0,0 +1,468 @@ +:B~ Dostosowywanie zdarzeń podczas uruchamiania systemu + +1~customizing-run-time-behaviours Dostosowywanie zdarzeń podczas +uruchamiania systemu + +Cała konfiguracja, która odbywa się w czasie pracy systemu jest wykonywana +przez live-config. Oto niektóre z najbardziej popularnych opcji live-config, +którymi mogą być zainteresowani użytkownicy. Pełną listę wszystkich +możliwości można znaleźć w podręczniku man pakietu live-config. + +2~ Personalizacja użytkownika live + +Jednym ważnym czynnikiem jest to, że użytkownik jest tworzony przez +live-boot w czasie startu systemu, a nie live-build w czasie kompilacji. To +wpływa nie tylko, na to gdzie materiały dotyczące użytkownika live są +wprowadzone w kompilacji, jak to opisano w {Uwzględnianie lokalne +Live/chroot}#live-chroot-local-includes, ale również na wszelkie grupyi +uprawnienia związane z użytkownikiem live. + +Można określić dodatkowe grupy, do których użytkownik live będzie należeć +korzystając z jednej z możliwości, aby skonfigurować live-config. Na +przykład, aby dodać użytkownika live do grupy #{fuse}#, można dodać +następujący plik w +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +lub użyj +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +jako parametru startowego. + +Możliwe jest również, aby zmienić domyślną nazwę użytkownika "user" i +domyślne hasło "live". Jeśli chcesz to zrobić, z jakiegokolwiek powodu, +można to łatwo osiągnąć w następujący sposób: + +Aby zmienić domyślną nazwę użytkownika należy po prostu określić ją w +konfiguracji: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +Jednym z możliwych sposobów zmiany domyślnego hasła jest użycie +odpowiedniego haka, jak opisano w {Haki podczas uruchamiania +systemu}#boot-time-hooks. W tym celu można użyć haka "passwd" z +#{/usr/share/doc/live-config/examples/hooks}#, przedrostkiem jest +odpowiednio (np. 2000-passwd), należy go dodać do +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Ustawianie lokalizacji i języka + +Podczas uruchamiania systemu live, język jest definiowany przez dwa etapy: + +_* generowanie plików lokalizacji + +_* ustawienie konfiguracji klawiatury + +Domyślne ustawieniem lokalnym podczas budowania systemu live jest +#{locales=en_US.UTF-8}#. Aby określić ustawienia regionalne, które powinny +być wygenerowane, użyj parametru #{locales}# w opcji #{--bootappend-live}# +polecenia #{lb config}#, np. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Wiele lokalizacji może być określone w postaci listy rozdzielonej +przecinkami. + +Parametr ten, jak również parametr konfiguracyjny klawiatury jak wskazano +poniżej, może być również używany w linii poleceń jądra. Można określić +ustawienia regionalne poprzez #{language_country}# (w tym przypadku używane +jest kodowanie domyślne) lub pełnej nazwy z kodowaniem +#{language_country.encoding}#. Lista obsługiwanych lokalizacji i kodowań +można znaleźć w #{/usr/share/i18n/SUPPORTED}#. + +Zarówno konfiguracja konsoli i klawiatury X wykonywana jest przez +#{live-config}# przy pomocy pakietu #{console-setup}#. Aby je skonfigurować, +ustaw parametry startowe #{keyboard-layouts}#, #{keyboard-variants}#, +#{keyboard-options}# i #{keyboard-model}# przez opcję +#{--bootappend-live}#. Prawidłowe wartośći opcje można znaleźć w +#{/usr/share/X11/xkb/rules/base.lst}#. Aby znaleźć układy i warianty +klawiatury dla danego języka, spróbuj wyszukać nazwę w języku angielskim +i/lub kraj, gdzie mówi się danym językiem, np.: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Należy pamiętać, że każdy wariant wymienia układ, którego dotyczy w opisie. + +Często tylko układ klawiatury musi być skonfigurowany. Na przykład, aby +uzyskać listę plików lokalizacyjnych dla niemieckiego i szwajcarskiego +niemieckiego układu klawiatury w systemie X użyj: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +Jednak dla bardzo konkretnych przypadków użycia, można dodać inne +parametry. Na przykład, aby ustawić francusko języczny system z układem +klawiatury French-Dvorak (zwany Bepo) na klawiaturze typu USB TypeMatrix +EZ-Reach 2030, użyj: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Wiele wartości oddzielonych przecinkami może być przypisane do każdego z +parametrów #{keyboard-*}#, z wyjątkiem #{keyboard-model}#, który przyjmuje +tylko jedną wartość. Proszę przejrzeć podręcznik man #{keyboard(5)}# aby +uzyskać więcej szczegółów i przykładów zmiennych #{XKBMODEL}#, +#{XKBLAYOUT}#, #{XKBVARIANT}# i #{XKBOPTIONS}#. Jeśli podano wiele +#{keyboard-variants}# (ang warianty klawiatury), będą one dopasowane jeden +do drugiego przez wartość #{keyboard-layouts}# (patrz opcja #{setxkbmap(1)}# +#{-variant}#). Puste wartości są dozwolone; na przykład aby zdefiniować dwa +układy, domyślny US QWERTY oraz drugi US Dvorak, zastosuj: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistence + +Odmianą Live CD jest preinstalowany system, który uruchamia się z nośników +tylko do odczytu, takich jak cdrom, gdzie operacje zapisu i modyfikacje nie +przetrwają restartów sprzętowych hosta, na którym jest uruchomiony. + +System live jest uogólnieniem tego paradygmatu, a tym samym wspiera media +inne prócz płyt CD; ale dalej jako jego domyślne zachowanie, należy uważać +operacje tylko do odczytu a wszekie zmiany, w czasie działania są tracone +podczas zamykania systemu. + +'Persistence' (ang. trwałość) to wspólna nazwa dla różnych rodzajów +rozwiązań dla zapisania niektórych lub wszystkich danych między restartami +podczas używania i wprowadzania zmian do systemu. Aby zrozumieć, jak to +działa to przydatna była by wiedza, że nawet wtedy, gdy system jest +uruchamiany i działa z nośnika tylko do odczytu, to modyfikacje plików i +katalogów są zapisywane na zapisywalnych nośnikach, typowo dysk RAM (tmpfs) +a dane w pamięci RAM nie przetrwają restartu. + +Dane przechowywane na tym ramdysku powinny być przechowywane na zapisywalnym +trwałym nośniku takim jak lokalny dysk, lokalny udział sieciowy lub nawet na +sesji wielosesyjnego dysku CD-RW/DVD-RW. Wszystkie te nośniki są obsługiwane +w systemach live na różne sposoby i wszystkie, oprócz ostatniej wymagają +specjalnego parametru startowego określonego w czasie startu systemu: +#{persistence}#. + +Jeśli ustawiony jest parametr startowy #{persistence}# (a #{nopersistence}# +nie jest ustawiony), lokalne nośniki (np. dyski twarde, napędy USB) będą +przeszukane w celu znalezienia woluminów trwałości podczas startu +systemu. Możliwe jest ograniczenie, jakiego typu woluminy trwałości będą +wykorzystane przez określenie pewnych parametrów startowych opisanych w +podręczniku man live-boot(7). Wolumin trwałości może być każdym z +wymienionych: + +_* partycja, identyfikowana po nazwie GPT. + +_* system plików, identyfikowany po etykiecie. + +_* plik obrazu zlokalizowany na każdym obsługiwanym systemie plików (nawet +na partycji NTFS innego systemu), identyfikowany po nazwie pliku. + +Etykietą dla woluminu musi być #{persistence}#, ale będzie ignorowane, +dopóki nie będzie zawarty w katalogu głównym plik o nazwie +#{persistence.conf}#, który jest używany by pełni dostosować wolumin +persistence, to znaczy, że wskazuje się w nim katalogi, w których chcesz +zapisać na woluminie zmiany przy restarcie. Zobacz {Plik +persistence.conf}#persistence-conf, aby uzyskać więcej szczegółów. + +Oto kilka przykładów, jak przygotować wolumin, aby mógł być on użyty z opcją +persistence. Może to być, na przykład, partycja ext4 na dysku twardym lub na +nośniku wymiennym stworzona przez, np.: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +Zobacz również {Wykorzystanie przestrzeni pozostałej na nośniku +USB}#using-usb-extra-space. + +Jeśli masz już partycję na urządzeniu, można po prostu zmienić jego etykietę +używając następującego polecenia: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Oto przykład, jak stworzyć plik obrazu opartego na ext4 do zastosowania z +opcją persistance: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Po utworzeniu pliku obrazu, na przykład, aby sprawić by katalog #{/usr}# był +prwały, ale tylko zapisywał zmiany wprowadzone w tym katalogu, a nie całą +zawartość #{/usr}#, można użyć opcji "union". Jeśli plik obrazu znajduje się +w katalogu domowym, należy skopiować go do katalogu głównego systemu plików +na dysku twardym i zamontować go w #{/mnt}# w następujący sposób: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Następnie utwórz plik #{persistence.conf}# dodając zawartość i odmontowując +plik obrazu. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Teraz uruchom ponownie i wybierz nośnik live, a następnie uruchom dodając +parametr startowy "persistence". + +3~persistence-conf Plik persistence.conf + +Partycję z etykietą #{persistence}# należy skonfigurować za pomocą pliku +#{persistence.conf}#, aby dowolne katalogi stały się trwałe. Ten plik, +znajdujący się w głównym katalogu systemu plików partycji, kontroluje które +katalogi są trwałe i w jaki sposób. + +To jak niestandardowe wierzchnie zamontowania są skonfigurowane jest opisane +w szczegółach w podręczniku man persistence.conf(5), ale ten prosty przykład +powinien być wystarczający dla większości zastosowań. Powiedzmy, że chcemy, +aby nasz katalog domowy i cache APT było trwałe w pamięci podręcznej systemu +plików ext4 na partycji /dev/sdb1: + +code{ + +# mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Następnie uruchamiamy ponownie komputer. Podczas pierwszego uruchomienia +zawartość #{/home}# i #{/var/cache/apt}# zostanie skopiowana do woluminu +trwałości i od tej pory wszystkie zmiany w tych katalogach będą +przechowywane na tym woluminie. Należy pamiętać, że wszelkie ścieżki +wymienione w pliku #{persistence.conf}# nie mogą zawierać spacji lub +specjalnych komponentów ścieżki: #{.}# i #{..}# . Ponadto, ani #{/lib}#, +#{/lib/live}# (lub którykolwiek z jego podkatalogów) ani #{/}# nie może +zostać utrwalony za pomocą własnych punktów montowania. Jako obejście tego +ograniczenia można dodać #{/ union}# do pliku #{persistence.conf}# w celu +osiągnięcia pełnej trwałości. + +3~ Używanie więcej niż jednego magazynu persistence + +Istnieją różne sposoby korzystania z wielu magazynów trwałości +(ang. persistence) dla różnych zastosowań. Na przykład, przy używanie kilku +magazynów w tym samym czasie lub wybranie tylko jednego, spośród różnych, do +bardzo specyficznych zastosowań. + +Kilka różnych niestandardowych woluminów-nakładek (z własnymi plikami +#{persistence.conf}#) może być używane w tym samym czasie, ale jeżeli kilka +woluminów tworzy ten sam katalog trwałym, będzie używany tylko jeden z +nich. Jeśli jakieś dwa punty montowania są "zagnieżdżone" (np. jeden jest +podkatalogiem drugiego) to katalog parent (ang. rodzic) zostanie zamontowany +przed katalogiem child (ang. dziecko) tak że jeden punkt montowania nie +będzie ukryty przed innym. Zagnieżdżone niestandardowe woluminy są +problematyczne, jeżeli są wymienione w tym samym pliku +#{persistence.conf}#. Zobacz podręcznik man persistence.conf(5), jak radzić +sobie z tym przypadkiem, jeśli naprawdę potrzebujesz (Wskazówka: zazwyczaj +nie potrzebujesz). + +Jednym z możliwych przypadków użycia: Jeśli chcesz przechowywać dane +użytkownika np. #{/home}# i dane superużytkownika tj. #{/root}# na różnych +partycjach, utwórz dwie partycje z etykietą #{persistence}# i dodaj plik +#{persistence.conf} na każdą z nich, tak #{# echo "/home" > +persistence.conf}# na pierwszej partycji, przez co będzą zapisywane pliki +użytkownika i #{# echo "/root" > persistence.conf}# na drugiej partycji, +która będzie przechowywać pliki superużytkownika. Wreszcie, należy użyć +parametru startowego #{persistence}#. + +Jeśli użytkownik będzie potrzebował wiele magazynów trwałości tego samego +typu dla różnych miejsc lub dla celów testowych, takich jak magazyny +#{private}# i #{work}# parametr startowy #{persistence-label}# użyty w +połączeniu z parametrem #{persistence}# pozwoli na wiele unikatowych +magazynów trwałości. Przykładem może być, jeśli użytkownik chciałby użyć +partycji trwałości oznaczonej #{private}# dla prywatnych danych, takich jak +zakładki w przeglądarce lub innych typów danych, to mógłby użyć parametrów +startowych:#{persistence}# #{persistence-label=private}#. A do +przechowywania danych związanych z pracą, takich jak dokumenty, projekty +badawcze lub inne rodzaje, mógłby skorzystać z parametrów startowych: +#{persistence}# #{persistence-label=work}#. + +Ważne jest, aby pamiętać, że każda z tych partycji, #{private}# i +#{work}#, także potrzebuje pliku #{persistence.conf}#. Podręcznik man +pakietu live-boot zawiera więcej informacji o tym, jak korzystać z tych +etykiet z zapisanymi nazwami. + +3~ Using persistence with encryption + +Korzystanie z funkcji trwałości (ang. persistence) oznacza, że niektóre +poufne dane mogą zostać narażone na ryzyko. Zwłaszcza jeśli trwałe dane są +przechowywane na urządzeniu przenośnym, takim jak pamięci USB lub zewnętrzne +dyski twarde. To jest miejsce, gdzie przydatne staje się szyfrowanie. Nawet +jeśli cała procedura może wydawać się skomplikowana, ze względu na liczbę +kroków, które należy podjąć, to jest bardzo łatwo obsługiwać szyfrowane +partycje z live-boot. Aby móc korzystać z *{luks}*, który jest obsługiwanym +typem szyfrowania, musisz zainstalować /{cryptsetup}/ zarówno na maszynie +tworzenia zaszyfrowanych partycji, a także w systemie live, który będzie +używał szyfrowanej trwałej partycji. + +Aby zainstalować /{cryptsetup}/ na twoim komputerze: + +code{ + + # apt-get install cryptsetup + +}code + +Aby zainstalować /{cryptsetup}/ na twoim systemie live dodaj go do listy +pakietów: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Gdy Twoj system live posiada /{cryptsetup}/, to w zasadzie wystarczy, już +tylko utworzyć nową partycję, zaszyfrować ją i uruchomić z parametrami +#{persistence}# i #{persistence-encryption=luks}#. Mogliśmy już przewidzieć +ten krok i dodać parametry startowe w czasie kompilacji przestrzegając +następującej procedury: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +przejdzmy do szczegółów dla tych wszystkich, którzy nie są zaznajomieni z +szyfrowaniem. W poniższym przykładzie mamy zamiar użyć partycji na dysku +USB, która odpowiada #{/dev/sdc2}#. Należy zaznaczyć, że należy ustalić, +która partycja jest jeden tą, którą masz zamiar używać w tym konkretnym +przypadku. + +Pierwszym krokiem jest podłączenie dysku USB i określenie, którym jest +urządzeniem. Zalecaną metodą tworzenia listy urządzeń w live-manual jest +#{ls -l /dev/disk/by-id}#. Następnie utworzymy nową partycję, a następnie +zaszyfrujemy ją hasłem w następujący sposób: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Następnie otwieramy partycję LUKS w wirtualnym elemencie odwzorowującym +urządzenia *{/dev/mapper}*. Można tu użyć dowolnej nazww. Używamy *{live}* +jako przykład: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +Następnym krokiem jest wypełnienie urządzenia zerami przed utworzeniem +systemu plików: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Teraz jesteśmy gotowi do stworzenia systemu plików. Warto zauważyć, że +dodajemy etykietę #{persistence}# tak, aby urządzenie zotało zamontowane w +jako persistence store (magazyn persistence) w czasie startu systemu. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +Aby kontynuować naszą konfigurację, musimy zamontować urządzenie, na +przykład w #{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +I stwórz plik #{persistence.conf}# w katalogu głównym partycji. To jest, jak +wyjaśniono wyżej, absolutnie konieczne. Zobacz {Plik +persistence.conf}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Potem odmontuj punkt montowania: + +code{ + + # umount /mnt + +}code + +I opcjonalnie, choć może to być dobry sposób na zabezpieczenie danych, które +właśnie dodaliśmy do partycji, możemy zamknąć urządzenie: + +code{ + + # cryptsetup luksClose live + +}code + +Podsumujmy proces. Do tej pory stworzyliśmy system live z możliwością +szyfrowania, który można skopiować na nośnik usb, jak wyjaśniono w +{kopiowaniu hybrydowego obrazu ISO na nośnik pamięci +USB}#copying-iso-hybrid-to-usb. Stworzyliśmy również zaszyfrowaną partycję, +która może znajdować się na tym samym nośniku usb, aby można było go nosić +ze sobą wszędzie i mamy skonfigurowaną zaszyfrowaną partycję, stosowaną jako +magazyn persistence. Więc teraz, musimy tylko uruchomić system live. W +czasie startu systemu, na live-boot poprosi nas o wpisanie hasła i zamontuje +zaszyfrowaną partycję używaną przez opcję persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_installation.ssi new file mode 100644 index 0000000..250f920 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_installation.ssi @@ -0,0 +1,181 @@ +:B~ Instalacja + +1~installation Instalacja + +2~requirements Wymagania + +Budowanie obrazów systemu live ma bardzo niewielkie wymagania systemowe: + +_* Dostęp do konta (root) super-użytkownika + +_* Aktualna wersja live-build + +_* Powłoka zgodna z POSIX, taka jak /{bash}/ lub /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6 lub nowszy. + +Należy pamiętać, że użycie Debiana lub dystrybucji pochodzącej od Debian nie +jest wymagane - live-build będzie działać na prawie każdej dystrybucji +spełniającej powyższe wymagania. + +2~installing-live-build Instalowanie live-build + +Możesz zainstalować live-build na wiele różnych sposobów: + +_* Z repozytorium Debiana + +_* Ze źródła + +_* Ze zrzutów deweloperskich + +Jeśli używasz Debiana, zalecanym sposobem jest zainstalowanie live-build +poprzez repozytorium Debiana. + +3~ Z repozytorium Debiana + +Zwyczajnie zainstaluj live-build jak każdą inną paczkę: + +code{ + + # apt-get install live-build + +}code + +3~ Ze źródła + +live-build jest opracowana z wykorzystaniem systemu kontroli wersji Git. W +systemach opartych na Debianie, jest on dostarczany przez pakiet +/{git}/. Aby sprawdzić najnowszy kod, wykonaj: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +Możesz zbudować i zainstalować własną paczkę Debiana wykonując: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Teraz zainstaluj którąkolwiek świeżo zbudowaną paczkę #{.deb}, wedle wyboru, +np. + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +Możesz również zainstalować live-build bezpośrednio w swoim systemie +wykonując: + +code{ + + # make install + +}code + +i odinstalować go wykonując: + +code{ + + # make uninstall + +}code + +3~ Ze zrzutów deweloperskich + +Jeśli nie chcesz, kompilować i zainstalować live-build ze źródła, możesz +użyć zrzutów deweloperskich. Są to automatycznie zbudowane paczki z +najnowszej wersji Git i są one dostępne na http://live-systems.org/debian/. + +2~ Instalowanie live-boot i live-config + +*{Uwaga:}* Nie musisz instalować live-boot lub live-config w systemie do tworzenia niestandardowych systemów żywych. Jednak ten sposób nie zaszkodzi i jest przydatny do celów porównawczych. Jeśli chcesz tylko przejrzeć dokumentację, możesz zainstalować pakiety /{live-boot-doc}/ i /{live-config-doc}/ oddzielnie. + +3~ Z repozytorium Debiana + +Zarówno live-boot oraz live-config są dostępne w repozytorium Debiana, tak +jak w {Instalacji live-build}#installing-live-build. + +3~ Ze źródła + +Aby używać najnowszych źródeł z repozytorium GIT, użyj poniższego +polecenia. Proszę upewnij się, że zapoznałeś się z warunkami wymienionymi w +{Warunkach}#terms. + +_* Sklonuj źródła live-boot i live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Poradź się podręcznikiem man pakietół live-boot i live-config aby uzyskać +szczegółowe informacje na temat dostosowywania, jeżeli to jest Twój powód do +budowania tych pakietów ze źródeł. + +_* Zbuduj pliki .deb live-boot i live-config + +Musisz budować obraz albo na dystrybucji docelowej lub w środowisku chroot +zawierającym platformę docelowej: oznacza to, czy celem jest ${testing} to +obraz należy budować na ${testing}. + +Używaj osobistych konstruktorów takich jak /{pbuilder}/ lub /{sbuild}/, +jeżeli istnieje potrzeba zbudowania live-boot na dystrybucji docelowej, +która różni się od systemu budowania. Na przykład, dla obrazów ${testing} +live, zbuduj live-boot w środowisku chroot ${testing}. Jeśli dystrybucja +docelowa zgadza się z dystrybucją systemu kompilacji, można wtedy zbudować +bezpośrednio na wbudowanym systemie, używając #{dpkg-buildpackage}# +(dostarczanego przez pakiet /{dpkg-dev}/): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Użyj mających wygenerowanych plików .deb + +Przez to, że live-boot i live-config są instalowane przez system live-build, +instalacji pakietów w systemie gospodarza nie jest wystarczająca: należy +traktować wygenerowane pliki deb jak inne pakiety niestandardowe.. Ponieważ +z reguły celem budowania ze źródła jest testowanie nowe rzeczy w krótkim +okresie przed oficjalną premierą, poinstruuj się {Instalowanie +zmodyfikowanych paczek innych +firm}#installing-modified-or-third-party-packages, aby tymczasowo umieścić +odpowiednie pliki w konfiguracji. W szczególności należy zauważyć, że oba +pakiety są podzielone na rodzajowe części, część dokumentacji i jeden lub +więcej części dodatkowych. Obejmują część rodzajową, tylko jeden back-end +(część dodatkowa) dopasowana do konfiguracji i ewentualnie część +dokumentacji. Zakładając, że budujesz obraz live w bieżącym katalogu i +wszystkie wygenerowane paczki .deb dla pojedynczej wersji obu pakietów +znajdują się w katalogu powyżej, te polecenia bash skopiują wszystkie +odpowiednie pakiety, w tym domyślne dla nich back-endy: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ Ze zrzutów deweloperskich + +Możesz pozwolić live-build automatycznie skorzystać z najnowszych zrzutów +deweloperskich live-boot i live-live-config przez skonfigurowanie +repozytorium pakietu live-systems.org jako repozytorium innych firm w +katalogu konfiguracyjnym live-build. diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_managing_a_configuration.ssi new file mode 100644 index 0000000..1b367d5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_managing_a_configuration.ssi @@ -0,0 +1,142 @@ +:B~ Zarządzanie konfiguracją + +1~managing-a-configuration Zarządzanie konfiguracją + +Ten rozdział wyjaśnia, jak zarządzać konfiguracją live od początku jej +tworzenia, przez kolejne zmiany i kolejne wersje oprogramowania live-build i +obrazu live. + +2~ Radzenie sobie ze zmianami konfiguracji + +Konfiguracje live rzadko są idealne na przy pierwszej próbie. Powinno się +dodać opcje #{lb config}# z linii poleceń do wykonania pojedynczej +kompilacji, ale bardziej typowe jest sprawdzać te opcje i kompilować +ponownie aż do uzyskania satysfakcji. Aby poradzić sobie z tymi zmianami, +potrzeba automatycznych skryptów, które zapewnią, że konfiguracja +przechowywana jest w stanie spójnym. + +3~ Czemu używać automatycznych skryptów? Co one robią? + +Polecenie #{lb config}# zapisuje opcje, które są wprowadzane do plików w +#{config}/*# oraz wielu innym opcją przypisuje wartości domyślne. Jeśli +uruchomisz #{lb config}# ponownie, nie skasuje to żadnych opcji, która +została zapisana na podstawie początkowych opcji. Tak więc, na przykład, +jeśli by uruchomić #{lb config}# ponownie z nową wartością dla +#{--binary-images}#, wszelkie opcje zależne, które zostały przypisane jako +domyślne dla poprzedniej dystrybucji mogą już nie współgrać z nowym +ustawieniem. Pliki te nie są przeznaczone do odczytu lub edycji. Przechowują +one wartości dla ponad stu opcji, więc nikt, nie mówiąc już o robieniu tego +w pojedynkę, nie będzie mógł zobaczyć, które z tych opcji są faktycznie +przypisane. I wreszcie, po uruchomieniu #{lb config}#, a następnie +uaktualnieniu live-build a zdarza się, że zmieniają się nazwy opcji, +#{config/*}# nadal będzie zawierać zmienne nazwane po staremu, które nie są +już aktualne. + +Z tych wszystkich powodów, skrypty #{auto/*}# czynią Twoje życie +łatwiejszym. Są proste wrappery do poleceń #{lb config}#, #{lb build}# i +#{lb clean}#, które są zaprojektowane, aby pomóc w zarządzaniu +konfiguracją. Skrypt #{auto/config}# przechowuje toje polecenie #{lb +config}# ze wszystkimi pożądanymi opcjami, skrypt #{auto/clean}# usuwa pliki +zawierające wartości zmiennych konfiguracyjnych a skrypt #{auto/build}# +zachowuje log #{build.log}# każdej kompilacji. Każdy z tych scenariuszy jest +uruchamiany automatycznie przy każdym uruchomieniu odpowiedniego polecenia +#{lb}#. Korzystając z tych skryptów, konfiguracja jest bardziej czytelna i +jest przechowywana w sposoób wewnętrznie spójny z jednej wersji do +następnej. Ponadto, będzie o wiele łatwiej zidentyfikować opcje, które +należy zmienić po uaktualnieniu live-build i po przeczytaniu dokumentacji +aktualizacji. + +3~ Użyj przykładowych automatycznych skryptów + +Dla Twojej wygody, live-build jest dostarczany z przykładowymi skryptami +powłoki do automatycznego kopiowania i edycji. Rozpocznij nową, domyślną +konfigurację, a następnie skopiuj do niej przykłady: + +code{ + + $ mkdir mójlive && cd mójlive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Edytuj #{auto/config}#, dodając wszelkie opcje, jakie uważasz. Przykładowo: + +code{ + +#!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Teraz, za każdym razem kiedy korzystasz z #{lb config}#, #{auto/config}# +skasuje konfigurację w oparciu o te opcje. Gdy chcesz wprowadzić zmiany do +nich, należy edytować opcje w tym pliku zamiast przekazywać je do #{lb +config}#. Podczas korzystania z #{lb clean}#, #{auto/clean}# oczyści pliki w +#{config/*}# wraz z innymi produktami kompilacji. I wreszcie, kiedy używasz +#{lb build}#, log kompilacji zostanie zapisany przez #{auto/build}# w +#{build.log}#. + +*{Uwaga:}* Specjalnny parametr #{noauto}# jest użyty tutaj, aby powstrzymać kolejne zapytania do #{auto/config}#, zapobiegając w ten sposób nieskończonej rekurencji. Upewnij się, że przypadkowo nie został usunięty podczas dokonywania zmiany. Również należy zadbać o to aby podczas dzielenia polecenia #{lb config}# na wiele lini dla czytelności, jak pokazano w powyższym przykładzie, nie zapomnisz odwrotnego ukośnika (\) na końcu każdej linii, która kontynuuje polecenie w następnej linijce. + +2~clone-configuration-via-git Klonowanie konfiguracji opublikowanej przez +Git + +Użyj opcji #{lb config --config}# aby sklonować repozytorium Git, który +zawiera konfigurację systemu live. Jeśli chcesz oprzeć swoją konfigurację na +jednej dostarczanej przez ${project}, odwiedź +http://live-systems.org/gitweb/ i szukaj repozytorium o nazwie +#{live-images}# (obrazy live) w kategorii #{Packages}# (pakiety). To +repozytorium zawiera konfiguracje dla {prekompilowanych +obrazów}#downloading-prebuilt-images systemów live. + +For example, to build a standard image, use the #{live-images}# repository +as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Edytuj #{auto/config}# i wszelkie inne rzeczy, których wymagasz do +własnych potrzeb w drzewie katalogów #{config}#. Na przykład, nie +nieoficjalne prekompilowane obrazy tworzy się dodając po prostu +#{--archive-areas "main contrib non-free"}#. + +Opcjonalnie można zdefiniować skrót w konfiguracji Git przez dodanie +następujących opcji do #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +Dzięki temu można skorzystać z #{lso:}# wszędzie, gdzie trzeba podać adres +repozytorium git #{live-systems.org}#. Jeśli również opuścisz opcjonalny +przyrostek #{.git}#, rozpoczynając nowy obraz przy użyciu tej konfiguracji +jest to tak proste: + +code{ + + $ lb config --config lso:live-images + +}code + +Klonowanie całego repozytorium #{live-images}# (obrazów live) sciąga +konfigurację używaną dla kilku różnych obrazów. Jeśli masz ochotę na budowę +innego obrazu po zakończeniu pracy z pierwszym, przejdź do innego katalogu i +ponownie w miarę potrzeb dokonaj zmian. + +W każdym przypadku należy pamiętać, że za każdym razem trzeba będzie budować +obraz jako super-użytkownik: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/pl/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/pl/user_overview.ssi new file mode 100644 index 0000000..4ad9496 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pl/user_overview.ssi @@ -0,0 +1,132 @@ +:B~ Przegląd narzędzi + +1~overview-of-tools Przegląd narzędzi + +Ten rozdział zawiera przegląd trzech głównych narzędzi stosowanych w budowie +systemów live: live-build, live-boot i live-config. + +2~live-build Pakiet live-build + +Iive-build to zbiór skryptów do budowania systemów live. Skrypty te są +również określane jako "polecenia". + +Pomysłem stojącym za live-build jest bycie oprawą, która używa struktury +katalogów jako konfiguracji, aby całkowicie zautomatyzować i dostosować +wszystkie aspekty budowania obrazu live. + +Wiele pojęć jest podobnych do tych używanych do budowania pakietów Debiana z +użyciem /{debhelper}/'a: + +_* Skrypty posiada centralną lokalizację dla konfiguracji ich działania. Dla +/{debhelper}/'a jest to podkatalog drzewa pakietów #{debian/}#. Na przykład, +dh_install będzie szukać, spośród innych, pliku o nazwie #{debian/install}# +do określenia, które pliki powinny zawierać się w określonym pakiecie +binarnym. W taki sam sposób, live-build przechowuje swoją konfigurację w +całości w podkatalogu #{config/}#. + +_* Skrypty są niezależne - to znaczy, że zawsze jest bezpieczne uruchomienie +poszczególnych poleceń. + +W przeciwieństwie do /{debhelpera}/, live-build zapewnia narzędzia do +generowania szkieletu katalogów konfiguracyjnych. Może to być uznane za +podobne do narzędzi takich jak /{dh-make}/. Aby uzyskać więcej informacji na +temat tych narzędzi, kontynuuj czytanie, ponieważ pozostała część tego +rozdziału omawia cztery najważniejsze polecenia. Należy zauważyć, że głównym +wrapperem dla polecenia live-build jest #{lb}#. + +_* *{lb config}*: Odpowiedzialny za inicjowanie katalogu konfiguracji +systemu live. Zobacz {Polecenie lb config}#lb-config, aby uzyskać więcej +informacji. + +_* *{lb build}*: Odpowiedzialny za rozpoczęcie kompilacji systemu +live. Zobacz {polecenie lb build}#lb-build aby uzyskać więcej informacji. + +_* *{lb clean}*: Odpowiedzialny za czyszczenie kompilacji systemu +live. Zobacz {polecenie lb clean}#lb-clean aby uzyskać więcej informacji. + +3~lb-config Polecenie #{lb config}# + +Jak omówiono w {live-build}#live-build, skrypty, które składają się na +live-build czytają swoją konfigurację przy użyciu polecenia #{source}# z +katalogu o nazwie #{config/}#. Budowanie tego katalogu ręcznie byłoby +czasochłonne i podatne na błędy, polecenie #{lb config}# może być używane do +tworzenia początkowej konfiguracji drzewa katalogów. + +Wykonanie #{lb config}# bez żadnych argumentów tworzy podkatalog #{config}#, +w którym zapisane są niektóre domyślne ustawienia, w plikach +konfiguracyjnych, oraz dwa szkielety drzew o nazwach #{auto/}# i +#{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +2~ Wcięcia + +Normalnie, pewnie będziesz chciał określić niektóre opcje. Na przykład, aby +określić, jakiego menadżera pakierów chcesz użyć podczas budowania obrazu: + +code{ + + $ lb config --apt aptitude + +}code + +Jest możliwe ustalenie wielu opcji, takich jak: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +Pełna lista opcji dostępna jest w podręczniku man pakietu #{lb_config}#. + +3~lb-build Polecenie #{lb build}# + +Polecenie #{lb build}# czyta konfigurację z katalogu #{config/}#. A +następnie uruchamia polecenia niższego poziomu potrzebne do budowy Twojego +systemu live. + +3~lb-clean Polecenie #{lb clean}# + +Zadaniem polecenia #{lb clean}#, jest to aby usunąć różne części kompilacji +tak aby można było zacząć od czystego stanu. Domyślnie etapy #{chroot}#, +#{binary}# and #{source}# są sprzątane, ale cache pozostaje +nienaruszone. Ponadto, tylko poszczególne etapy mogą być oczyszcane. Na +przykład, jeśli zostały wprowadzone zmiany, które wpływają tylko na etap +binarny, należy użyć #{lb clean --binary}# przed budowaniem nowych plików +binarnych. Jeśli zmiany unieważniają proces bootstrap i/lub zmieniają cache +pakietów, np. po zmianie opcji #{--mode}#, #{--architecture}#, lub +#{--bootstrap}#, trzeba użyć #{lb clean --purge}#. Zobacz podręcznik man +pakietu #{lb_clean}# aby uzyskać listę wszystkich opcji. + +2~live-boot Pakiet live-boot + +live-boot to zbiór skryptów zapewniających haki do /{initramfs-tools}/, +wykorzystywane do wytwarzania plików initramfs, które są w stanie uruchomić +system live, takich jak te stworzone przez live-build. Obejmuje to obrazy +ISO systemów live, archiwa netboot i obrazów dysku USB. + +W czasie rozruchu będzie szukać nośników tylko do odczytu zawierających +katalog #{/live/}#, gdzie jest przechowywany system plików (często +skompresowany obraz systemu plików jak SquashFS). Jeśli znajdzie takowy, +stworzy zapisywalne środowisko, stosując aufs, dla systemów takich jak +Debian, aby z niego wystartować. + +Więcej informacji na temat początkowych plików ramfs w Debianie można +znaleźć w Podręczniku Debiana Linux Kernel na +http://kernel-handbook.alioth.debian.org/ w rozdziale initramfs. + +2~live-config Pakiet live-config + +live-config zawiera skrypty, które są uruchamiane przy starcie systemu live +po live-boot, tak aby automatycznie skonfigurować system live. Obsługuje on +takie zadania jak ustawienie nazwy hosta, lokalizacji i strefy czasowej, +tworzenie użytkownika live, zatrzymywanie zadań crona i autologowanie +użytkownika live. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_manual.ssi new file mode 100644 index 0000000..0741692 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_manual.ssi @@ -0,0 +1,269 @@ +:B~ Sobre esse manual + +1~about-manual Sobre esse manual + +This manual serves as a single access point to all documentation related to +the ${project} and in particular applies to the software produced by the +project for the Debian 9.0 "${stable}" release. An up-to-date version can +always be found at http://live-systems.org/ + +While live-manual is primarily focused on helping you build a live system +and not on end-user topics, an end user may find some useful information in +these sections: {The Basics}#the-basics covers downloading prebuilt images +and preparing images to be booted from media or the network, either using +the web builder or running live-build directly on your system. {Customizing +run time behaviours}#customizing-run-time-behaviours describes some options +that may be specified at the boot prompt, such as selecting a keyboard +layout and locale, and using persistence. + +Alguns comandos mencionados no texto devem ser executados com privilégios de +super-usuário, que podem ser obtidos tornando-se usuário root via #{su}# ou +usando #{sudo}#. Para distinção entre os comandos que talvez possam ser +executados como usuário não privilegiado e aqueles que requerem privilégios +de super usuário, os comandos são precididos por: #{$}# ou #{#}# +respectivamente. Esse simbolo não é parte do comando. + +2~ Para os impacientes + +Embora acreditemos que tudo neste manual é importante para pelo menos alguns +de nossos usuários, percebemos que tem muito material para cobertura e você +pode querer experimentar o sucesso precoce utilizando o software antes de se +aprofundar nos detalhes. Portanto, sugerimos a leitura na seguinte ordem. + +First, read this chapter, {About this manual}#about-manual, from the +beginning and ending with the {Terms}#terms section. Next, skip to the three +tutorials at the front of the {Examples}#examples section designed to teach +you image building and customization basics. Read {Using the +examples}#using-the-examples first, followed by {Tutorial 1: A default +image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and +finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these +tutorials, you will have a taste of what can be done with live systems. + +We encourage you to return to more in-depth study of the manual, perhaps +next reading {The basics}#the-basics, skimming or skipping {Building a +netboot image}#building-netboot-image, and finishing by reading the +{Customization overview}#customization-overview and the chapters that follow +it. By this point, we hope you are thoroughly excited by what can be done +with live systems and motivated to read the rest of the manual, +cover-to-cover. + +2~terms Terminologia + +_* *{Live system}*: An operating system that can boot without installation +to a hard drive. Live systems do not alter local operating system(s) or +file(s) already installed on the computer hard drive unless instructed to do +so. Live systems are typically booted from media such as CDs, DVDs or USB +sticks. Some may also boot over the network (via netboot images, see +{Building a netboot image}#building-netboot-image), and over the Internet +(via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). + +_* *{Live medium}*: As distinct from live system, the live medium refers to +the CD, DVD or USB stick where the binary produced by live-build and used to +boot the live system is written. More broadly, the term also refers to any +place where this binary resides for the purposes of booting the live system, +such as the location for the network boot files. + +_* *{${project}}*: The project which maintains, among others, the live-boot, +live-build, live-config, live-tools and live-manual packages. + +_* *{Sistema Hospedeiro}*: O ambiente usado para criar o sistema live. + +_* *{Sistema Destino}*: O ambiente usado para rodar o sistema live. + +_* *{live-boot}*: Uma coleção de scripts usados para inicializar sistemas +live. + +_* *{live-build}*: A collection of scripts used to build customized live +systems. + +_* *{live-config}*: Uma coleção de scripts usados para configurar um sistema +live durante o processo de boot. + +_* *{live-tools}*: A collection of additional scripts used to perform useful +tasks within a running live system. + +_* *{live-manual}*: Esse documento é mantido em um pacote chamado +live-manual. + +_* *{Instalador Debian (d-i)}*: O sistema oficial de instalação para a +distribuição Debian. + +_* *{Paramentros de inicialização}*: Parametros que podem ser inseridos no +prompt do bootloader para influenciar o kernel ou o live-config. + +_* *{chroot}*: O programa /{chroot}/, #{chroot(8)}#, nos habilita a rodar +simultâneamente diferentes instâncias do ambiente do GNU/Linux em um único +sistema sem reinicialização. + +_* *{Binary image}*: A file containing the live system, such as +live-image-i386.hybrid.iso or live-image-i386.img. + +_* *{Distribuição Destino}*: A distribuição em que o sistema live será +baseado. Isso pode diferir da distribuição do seu sistema host. + +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently +codenamed ${stable}, contains the latest officially released distribution of +Debian. The *{testing}* distribution, temporarily codenamed ${testing}, is +the staging area for the next *{stable}* release. A major advantage of using +this distribution is that it has more recent versions of software relative +to the *{stable}* release. The *{unstable}* distribution, permanently +codenamed sid, is where active development of Debian occurs. Generally, this +distribution is run by developers and those who like to live on the +edge. Throughout the manual, we tend to use codenames for the releases, such +as ${testing} or sid, as that is what is supported by the tools themselves. + +2~ Autores + +Lista de autores (em ordem alfabética) + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Contribuindo com esse documento + +This manual is intended as a community project and all proposals for +improvements and contributions are extremely welcome. Please see the section +{Contributing to the project}#contributing-to-project for detailed +information on how to fetch the commit key and make good commits. + +3~applying-changes Applying changes + +In order to make changes to the English manual you have to edit the right +files in #{manual/en/}# but prior to the submission of your contribution, +please preview your work. To preview the live-manual, ensure the packages +needed for building it are installed by executing: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Você também pode construir o live-manual a partir do primeiro nível do +diretório do seu Git checkout executando: + +code{ + + $ make build + +}code + +Since it takes a while to build the manual in all supported languages, +authors may find it convenient to use one of the fast proofing shortcuts +when reviewing the new documentation they have added to the English +manual. Using #{PROOF=1}# builds live-manual in html format, but without the +segmented html files, and using #{PROOF=2}# builds live-manual in pdf +format, but only the A4 and letter portraits. That is why using either of +the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: + +code{ + + $ make build PROOF=1 + +}code + +When proofing one of the translations it is possible to build only one +language by executing, e.g: + +code{ + + $ make build LANGUAGES=de + +}code + +Também é possível construir, por tipo de documento, por exemplo: + +code{ + + $ make build FORMATS=pdf + +}code + +Ou a combinação dos dois, por exemplo: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +After revising your work and making sure that everything is fine, do not use +#{make commit}# unless you are updating translations in the commit, and in +that case, do not mix changes to the English manual and translations in the +same commit, but use separate commits for each. See the +{Translation}#translation section for more details. + +3~translation Tradução + +In order to translate live-manual, follow these steps depending on whether +you are starting a translation from scratch or continue working on an +already existing one: + +_* Start a new translation from scratch + +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and +*{index.html.in.pot}* files in #{manual/pot/}# to your language with your +favourite editor (such as /{poedit}/) and send the translated #{.po}# files +to the mailing list to check their integrity. live-manual's integrity check +not only ensures that the #{.po}# files are 100% translated but it also +detects possible errors. + +_2* Once checked, to enable a new language in the autobuild it is enough to +add the initial translated files to #{manual/po/${LANGUAGE}/}# and run +#{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the +name of the language and its name in English between brackets. + +_* Continue with an already started translation + +_2* If your target language has already been added, you can randomly +continue translating the remaining .po files in #{manual/po/${LANGUAGE}/}# +using your favourite editor (such as /{poedit}/). + +_2* Do not forget that you need to run #{make commit}# to ensure that the +translated manuals are updated from the .po files and then you can review +your changes launching #{make build}# before #{git add .}#, #{git commit -m +"Translating..."}# and #{git push}#. Remember that since #{make build}# can +take a considerable amount of time, you can proofread languages individually +as explained in {Applying changes}#applying-changes + +After running #{make commit}# you will see some text scroll by. These are +basically informative messages about the processing status and also some +hints about what can be done in order to improve live-manual. Unless you see +a fatal error, you usually can proceed and submit your contribution. + +live-manual comes with two utilities that can greatly help translators to +find untranslated and changed strings. The first one is "make translate". It +launches an script that tells you in detail how many untranslated strings +there are in each .po file. The second one, the "make fixfuzzy" target, only +acts upon changed strings but it helps you to find and fix them one by one. + +Keep in mind that even though these utilities might be really helpful to do +translation work on the command line, the use of an specialized tool like +/{poedit}/ is the recommended way to do the task. It is also a good idea to +read the Debian localization (l10n) documentation and, specifically to +live-manual, the {Guidelines for translators}#guidelines-translators. + +*{Observação:}* Você pode usar #{make clean}# para limpar a sua árvore git antes de enviar. Este passo não é obrigatório graças ao gitignore., Mas é uma boa prática para evitar enviar arquivos involuntariamente. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_project.ssi new file mode 100644 index 0000000..e7a84b8 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/about_project.ssi @@ -0,0 +1,105 @@ +:B~ About the ${project} + +1~about-project About the ${project} + +2~ Motivação + +3~ O que está errado com os atuais sistemas live + +When ${project} was initiated, there were already several Debian based live +systems available and they are doing a great job. From the Debian +perspective most of them have one or more of the following disadvantages: + +_* Eles não são projetos Debian e, portanto, carecem de apoio de dentro do +Debian. + +_* Eles misturam diferentes distribuições, exemplo *{testing}* e +*{unstable}*. + +_* Eles suportam apenas i386. + +_* Eles modificam o comportamento e/ou a aparência de pacotes retirando-os +para economizar espaço. + +_* Eles incluem pacotes de fora dos arquivos Debian. + +_* Eles enviam kernels personalizados com correções adicionais que não fazem +parte do Debian. + +_* Eles são grandes e lentos devido ao seu tamanho e, portanto, inadequados +para questões de recuperação. + +_* Eles não estão disponíveis em diferentes sabores, ou seja, CDs, DVDs, +USB-stick e imagens netboot. + +3~ Por que criar seu proprio sistema live? + +Debian é o Sistema Operacional Universal que tem um sistema live para +mostrar e representar com precisão o sistema Debian com as principais +vantagens, a seguir: + +_* É um subprojeto do Debian. + +_* Reflete o estado (atual) de uma distribuição. + +_* Roda em tantas arquiteturas quanto possivel. + +_* É composto apenas por pacotes do Debian inalterados. + +_* Ele não contém pacotes que não estão no arquivo Debian. + +_* Ele usa um kernel inalterado Debian sem correções adicionais. + +2~ Filosofia + +3~ Apenas pacotes inalterados do Debian "main" + +Nós só usaremos pacotes do repositorio Debian seção "main". A seção non-free +não é parte do Debian e então não pode ser utilizada e, portanto, não pode +ser usada para imagens de sistemas live oficiais. + +Nós não vamos alterar qualquer pacote. Sempre que preciso mudar alguma +coisa, vamos fazer isso em coordenação com o seu mantenedor do pacote no +Debian. + +Como uma exceção, nossos próprios pacotes, como live-boot, live-build ou +live-config podem ser usados temporariamente do nosso próprio repositório, +por razões de desenvolvimento (por exemplo, para criar imagens instantanea +de desenvolvimento ). Eles serão enviados para o Debian em uma base regular. + +3~ Nenhum pacote de configuração do sistema live + +Nesta fase nós não enviaremos ou instalaremos exemplos ou configurações +alternativas. Todos os pacotes são usados em sua configuração padrão, como +eles estão atrás de uma instalação normal do Debian. + +Sempre que precisamos de uma configuração padrão diferente, vamos fazer isso +em coordenação com o seu mantenedor do pacote no Debian. + +A system for configuring packages is provided using debconf allowing custom +configured packages to be installed in your custom produced live system +images, but for the {prebuilt live images}#downloading-prebuilt-images we +choose to leave packages in their default configuration, unless absolutely +necessary in order to work in the live environment. Wherever possible, we +prefer to adapt packages within the Debian archive to work better in a live +system versus making changes to the live toolchain or {prebuilt image +configurations}#clone-configuration-via-git. For more information, please +see {Customization overview}#customization-overview. + +2~contact Contato + +_* *{Mailing list}*: The primary contact for the project is the mailing list +at https://lists.debian.org/debian-live/. You can email the list directly by +addressing your mail to debian-live@lists.debian.org. The list archives are +available at https://lists.debian.org/debian-live/. + +_* *{IRC}*: Diversos usuários e desenvolvedores estão presentes no canal +#debian-live em irc.debian.org (OFTC). Quando fizer uma pergunta sobre IRC, +por favor seja paciente para uma resposta. Se nenhuma resposta for dada, +favor enviar um email para a lista. + +_* *{BTS}*: O {Debian Bug Tracking System = Sistema de acompanhamento de +erros do Debian}https://www.debian.org/Bugs/ (BTS) contem detalhes de erros +informados por usuários e desenvolvedores. Para cada erro é dado um numero, +e é mantido ate que seja informado que foi resolvido. Para mais informações, +por favor veja {Reportando Erros}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/appendix_style-guide.ssi new file mode 100644 index 0000000..1bba13e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/appendix_style-guide.ssi @@ -0,0 +1,364 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account +when writing technical documentation for live-manual. They are divided into +linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers +of English. So as a general rule try to use short, meaningful sentences, +followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a +suggestion to try to avoid, as much as possible, complex subordinate +sentences that make the text difficult to understand for non-native speakers +of English. + +_* /{Variety of English}/ + +The most widely spread varieties of English are British and American so it +is very likely that most authors will use either one or the other. In a +collaborative environment, the ideal variety would be "International +English" but it is very difficult, not to say impossible, to decide on which +variety among all the existing ones, is the best to use. + +We expect that different varieties may mix without creating +misunderstandings but in general terms you should try to be coherent and +before deciding on using British, American or any other English flavour at +your discretion, please take a look at how other people write and try to +imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely +unrelated to live-manual. Technical writing should be as neutral as +possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make +references to the third person singular preferably use "they" rather than +"he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +Go straight to the point and do not wander around aimlessly. Give as much +information as necessary but do not give more information than necessary, +this is to say, do not explain unnecessary details. Your readers are +intelligent. Presume some previous knowledge on their part. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several +other languages. This implies that a number of people will have to do an +extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +As suggested before, it is almost impossible to standardize a collaborative +document into a perfectly unified whole. However, every effort on your side +to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Be descriptive}/ + +It is preferable to describe the point in one or several paragraphs than +merely using a number of sentences in a typical "changelog" style. Describe +it! Your readers will appreciate it. + +_* /{Dictionary}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not +know how to express certain concepts in English. But keep in mind that a +dictionary can either be your best friend or can turn into your worst enemy +if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million +words). Many of these words are borrowings from other languages. When +looking up the meaning of words in a bilingual dictionary the tendency of a +non-native speaker of English is to choose the one that sounds more similar +in their mother tongue. This often turns into an excessively formal +discourse which does not sound quite natural in English. + +As a general rule, if a concept can be expressed using different synonyms, +it is a good advice to choose the first word proposed by the dictionary. If +in doubt, choosing words of Germanic origin (Usually monosyllabic words) is +often the right thing to do. Be warned that these two techniques might +produce a rather informal discourse but at least your choice of words will +be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely +helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search +engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign +language you cannot help falling from time to time in the trap of the so +called "false friends", words that look similar in two languages but whose +meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may +convey a completely different meaning from what their individual words seem +to mean. Sometimes, idioms might be difficult to understand even for native +speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical +writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand +and above all contractions that try to imitate the spoken language. Not to +mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +It is important that authors test their examples before adding them to +live-manual to ensure that everything works as described. Testing on a clean +chroot or VM can be a good starting point. Besides, it would be ideal if the +tests were then carried out on different machines with different hardware to +spot possible problems that may arise. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, +after all, just an example. + +It is often better to use a line that only applies to a specific case than +using abstractions that may confuse your readers. In this case you can +provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some +potentially dangerous commands that, if misused, may cause data loss or +other similar undesirable effects. In this case you should provide a +thorough explanation of the possible side effects. + +_* /{External links}/ + +Links to external sites should only be used when the information on those +sites is crucial when it comes to understanding a special point. Even so, +try to use links to external sites as sparsely as possible. Internet links +are likely to change from time to time resulting in broken links and leaving +your arguments in an incomplete state. + +Besides, people who read the manual offline will not have the chance to +follow those links. + +_* /{Avoid branding and things that violate the license under which the +manual is published}/ + +Try to avoid branding as much as possible. Keep in mind that other +downstream projects might make use of the documentation you write. So you +are complicating things for them if you add certain specific material. + +live-manual is licensed under the GNU GPL. This has a number of implications +that apply to the distribution of the material (of any kind, including +copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence + of events. + + - Once you have somehow organized those ideas in your mind write a first + draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names + of the releases, such as ${testing} or sid, should not be capitalized + when referred to as code names. In order to check the spelling you can + run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, +1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup +below. + +If you have to enumerate a series of steps or stages in your description, +you can also use ordinal numbers: First, second, third ... or First, Then, +After that, Finally ... Alternatively you can use bulleted items. + +_* /{Markup}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to +process the text files and produce a multiple format output. It is +recommended to take a look at {SiSU's +manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get +familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to +highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to +remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account +when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the +translation rules that apply to their specific languages. Usually, +translation groups and mailing lists provide information on how to produce +translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +The role of the translator is to convey as faithfully as possible the +meaning of words, sentences, paragraphs and texts as written by the original +authors into their target language. + +So they should refrain from adding personal comments or extra bits of +information of their own. If they want to add a comment for other +translators working on the same documents, they can leave it in the space +reserved for that. That is, the header of the strings in the *{po}* files +preceded by a number sign *{#}*. Most graphical translation programs can +automatically handle those types of comments. + +_* /{TN, Translator's Note}/ + +It is perfectly acceptable however, to include a word or an expression in +brackets in the translated text if, and only if, that makes the meaning of a +difficult word or expression clearer to the reader. Inside the brackets the +translator should make evident that the addition was theirs using the +abbreviation "TN" or "Translator's Note". + +_* /{Impersonal sentences}/ + +Documents written in English make an extensive use of the impersonal form +"you". In some other languages that do not share this characteristic, this +might give the false impression that the original texts are directly +addressing the reader when they are actually not doing so. Translators must +be aware of that fact and reflect it in their language as accurately as +possible. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to +translators. Double check the meaning of suspicious false friends if in +doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* +files will find many markup features in the strings. They can translate the +text anyway, as long as it is translatable, but it is extremely important +that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in +the translation is the only way to score a 100% complete translation. And +even though it means more work at first because it might require the +intervention of the translators if the code changes, it is the best way, in +the long run, to identify what has already been translated and what has not +when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original +texts. Be careful to press the "Enter" key or type *{\n}* if they appear in +the original files. These newlines often appear, for instance, in the code +blocks. + +Make no mistake, this does not mean that the translated text needs to have +the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/examples.ssi new file mode 100644 index 0000000..193e283 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/examples.ssi @@ -0,0 +1,434 @@ +:B~ Exemplos + +1~examples Examples + +This chapter covers example builds for specific use cases with live +systems. If you are new to building your own live system images, we +recommend you first look at the three tutorials in sequence, as each one +teaches new techniques that will help you use and understand the remaining +examples. + +2~using-the-examples Using the examples + +To use these examples you need a system to build them on that meets the +requirements listed in {Requirements}#requirements and has live-build +installed as described in {Installing live-build}#installing-live-build. + +Note that, for the sake of brevity, in these examples we do not specify a +local mirror to use for the build. You can speed up downloads considerably +if you use a local mirror. You may specify the options when you use #{lb +config}#, as described in {Distribution mirrors used at build +time}#distribution-mirrors-build-time, or for more convenience, set the +default for your build system in #{/etc/live/build.conf}#. Simply create +this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your +preferred mirror. All other mirrors used in the build will be defaulted from +these values. For example: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 Tutorial 1: A default image + +*{Use case:}* Create a simple first image, learning the basics of live-build. + +In this tutorial, we will build a default ISO hybrid live system image +containing only base packages (no Xorg) and some live system support +packages, as a first exercise in using live-build. + +You can't get much simpler than this: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examine the contents of the #{config/}# directory if you wish. You will see +stored here a skeletal configuration, ready to customize or, in this case, +use immediately to build a default image. + +Now, as superuser, build the image, saving a log as you build with #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Assuming all goes well, after a while, the current directory will contain +#{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly +in a virtual machine as described in {Testing an ISO image with +Qemu}#testing-iso-with-qemu and {Testing an ISO image with +VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media +or a USB flash device as described in {Burning an ISO image to a physical +medium}#burning-iso-image and {Copying an ISO hybrid image to a USB +stick}#copying-iso-hybrid-to-usb, respectively. + +2~tutorial-2 Tutorial 2: A web browser utility + +*{Use case:}* Create a web browser utility image, learning how to apply customizations. + +In this tutorial, we will create an image suitable for use as a web browser +utility, serving as an introduction to customizing live system images. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Our choice of LXDE for this example reflects our desire to provide a minimal +desktop environment, since the focus of the image is the single use we have +in mind, the web browser. We could go even further and provide a default +configuration for the web browser in +#{config/includes.chroot/etc/iceweasel/profile/}#, or additional support +packages for viewing various kinds of web content, but we leave this as an +exercise for the reader. + +Build the image, again as superuser, keeping a log as in {Tutorial +1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: A personalized image + +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. + +Since we will be changing our personalized image over a number of revisions, +and we want to track those changes, trying things experimentally and +possibly reverting them if things don't work out, we will keep our +configuration in the popular #{git}# version control system. We will also +use the best practice of autoconfiguration via #{auto}# scripts as described +in {Managing a configuration}#managing-a-configuration. + +3~ First revision + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Edit #{auto/config}# to read as follows: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Perform #{lb config}# to generate the config tree, using the #{auto/config}# +script you just created: + +code{ + + $ lb config + +}code + +Now populate your local package list: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +First, #{--architectures i386}# ensures that on our #{amd64}# build system, +we build a 32-bit version suitable for use on most machines. Second, we use +#{--linux-flavours 686-pae}# because we don't anticipate using this image on +much older systems. Third, we have chosen the /{lxde}/ task metapackage to +give us a minimal desktop. And finally, we have added two initial favourite +packages: /{iceweasel}/ and /{xchat}/. + +Now, build the image: + +code{ + + # lb build + +}code + +Note that unlike in the first two tutorials, we no longer have to type +#{2>&1 | tee build.log}# as that is now included in #{auto/build}#. + +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are +satisfied it works, it's time to initialize our #{git}# repository, adding +only the auto scripts we just created, and then make the first commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Second revision + +In this revision, we're going to clean up from the first build, add the +/{vlc}/ package to our configuration, rebuild, test and commit. + +The #{lb clean}# command will clean up all generated files from the previous +build except for the cache, which saves having to re-download packages. This +ensures that the subsequent #{lb build}# will re-run all stages to +regenerate the files from our new configuration. + +code{ + + # lb clean + +}code + +Now append the /{vlc}/ package to our local package list in +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Build again: + +code{ + +# lb build + +}code + +Test, and when you're satisfied, commit the next revision: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Of course, more complicated changes to the configuration are possible, +perhaps adding files in subdirectories of #{config/}#. When you commit new +revisions, just take care not to hand edit or commit the top-level files in +#{config}# containing #{LB_*}# variables, as these are build products, too, +and are always cleaned up by #{lb clean}# and re-created with #{lb config}# +via their respective #{auto}# scripts. + +We've come to the end of our tutorial series. While many more kinds of +customization are possible, even just using the few features explored in +these simple examples, an almost infinite variety of different images can be +created. The remaining examples in this section cover several other use +cases drawn from the collected experiences of users of live systems. + +2~ A VNC Kiosk Client + +*{Use case:}* Create an image with live-build to boot directly to a VNC server. + +Make a build directory and create an skeletal configuration inside it, +disabling recommends to make a minimal system. And then create two initial +package lists: the first one generated with a script provided by live-build +named #{Packages}# (see {Generated package lists}#generated-package-lists), +and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and +/{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you +may need to re-add some recommended packages to make your image work +properly. + +An easy way to list recommends is using /{apt-cache}/. For example: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +In this example we found out that we had to re-include several packages +recommended by live-config and live-boot: #{user-setup}# to make autologin +work and #{sudo}# as an essential program to shutdown the system. Besides, +it could be handy to add #{live-tools}# to be able to copy the image to RAM +and #{eject}# to eventually eject the live medium. So: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# +and put a custom #{.xsession}# in it for the default user that will launch +/{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a +server at #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Build the image: + +code{ + + # lb build + +}code + +Enjoy. + +2~ A base image for a 128MB USB key + +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. + +When optimizing an image to fit a certain media size, you need to understand +the tradeoffs you are making between size and functionality. In this +example, we trim only so much as to make room for additional material within +a 128MB media size, but without doing anything to destroy the integrity of +the packages contained within, such as the purging of locale data via the +/{localepurge}/ package, or other such "intrusive" optimizations. Of +particular note, we use #{--debootstrap-options}# to create a minimal system +from scratch. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +To make the image work properly, we must re-add, at least, two recommended +packages which are left out by the #{--apt-recommends false}# option. See +{Tweaking APT to save space}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Now, build the image in the usual way: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration +produced a 110MB image. This compares favourably with the 192MB image +produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount +of space, the tradeoff being that you need to do an #{apt-get update}# +before using /{apt}/ in the live system. Dropping recommended packages with +#{--apt-recommends false}# saves some additional space, at the expense of +omitting some packages you might otherwise expect to be +there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal +system from the start. Not automatically including firmware packages with +#{--firmware-chroot false}# saves some space too. And finally, #{--memtest +none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ A localized GNOME desktop and installer + +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. + +We want to make an iso-hybrid image for i386 architecture using our +preferred desktop, in this case GNOME, containing all of the same packages +that would be installed by the standard Debian installer for GNOME. + +Our initial problem is the discovery of the names of the appropriate +language tasks. Currently, live-build cannot help with this. While we might +get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, +which can be used to dig it out of the task descriptions in tasksel-data, so +to prepare, make sure you have both of those things: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Now we can search for the appropriate tasks, first with: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +By this command, we discover the task is called, plainly enough, german. Now +to find the related tasks: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +At boot time we will generate the *{de_CH.UTF-8}* locale and select the +*{ch}* keyboard layout. Now let's put the pieces together. Recalling from +{Using metapackages}#using-metapackages that task metapackages are prefixed +#{task-}#, we just specify these language boot parameters, then add standard +priority packages and all our discovered task metapackages to our package +list as follows: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to +launch the installer from the live desktop. The #{586}# kernel flavour, +which is currently necessary for the launcher to work properly, will be +included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/pt_BR/live-manual.ssm new file mode 100644 index 0000000..399c76a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manual Live Systems" + +creator: + author: "Projeto Live Systems <debian-live@lists.debian.org>" + +rights: + copyright: "Copyright (C) 2006-2015 Live Systems Project" + license: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." + +date: + published: "2015-08-23" + +publisher: "Projeto Live Systems <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ Sobre + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Usuario + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Projeto + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Exemplos + +<< examples.ssi + +:B~ Apendice + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_bugs.ssi new file mode 100644 index 0000000..76a0eba --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_bugs.ssi @@ -0,0 +1,206 @@ +:B~ Reporting bugs + +1~bugs Reporting bugs + +Live systems are far from being perfect, but we want to make it as close as +possible to perfect - with your help. Do not hesitate to report a bug. It is +better to fill a report twice than never. However, this chapter includes +recommendations on how to file good bug reports. + +For the impatient: + +_* Always check first the image status updates on our homepage at +http://live-systems.org/ for known issues. + +_* Before submitting a bug report always try to reproduce the bug with the +*{most recent versions}* of the branch of live-build, live-boot, live-config +and live-tools that you're using (like the newest 4.x version of live-build +if you're using live-build 4). + +_* Try to give *{as specific information as possible}* about the bug. This +includes (at least) the version of live-build, live-boot, live-config, and +live-tools used and the distribution of the live system you are building. + +2~ Known issues + +Since Debian *{testing}* and Debian *{unstable}* distributions are moving +targets, when you specify either of them as the target system distribution, +a successful build may not always be possible. + +% FIXME: + +If this causes too much difficulty for you, do not build a system based on +*{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always +defaults to the *{stable}* release. + +Currently known issues are listed under the section 'status' on our homepage +at http://live-systems.org/. + +It is out of the scope of this manual to train you to correctly identify and +fix problems in packages of the development distributions, however, there +are two things you can always try: If a build fails when the target +distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work +either, revert to *{testing}* and pin the newer version of the failing +package from *{unstable}* (see {APT pinning}#apt-pinning for details). + +2~ Rebuild from scratch + +To ensure that a particular bug is not caused by an uncleanly built system, +please always rebuild the whole live system from scratch to see if the bug +is reproducible. + +2~ Use up-to-date packages + +Using outdated packages can cause significant problems when trying to +reproduce (and ultimately fix) your problem. Make sure your build system is +up-to-date and any packages included in your image are up-to-date as well. + +2~collect-information Collect information + +Please provide enough information with your report. Include, at least, the +exact version of live-build where the bug is encountered and the steps to +reproduce it. Please use your common sense and provide any other relevant +information if you think that it might help in solving the problem. + +To make the most out of your bug report, we require at least the following +information: + +_* Architecture of the host system + +_* Distribution of the host system + +_* Version of live-build on the host system + +_* Version of /{debootstrap}/ on the host system + +_* Architecture of the live system + +_* Distribution of the live system + +_* Version of live-boot on the live system + +_* Version of live-config on the live system + +_* Version of live-tools on the live system + +You can generate a log of the build process by using the #{tee}# command. We +recommend doing this automatically with an #{auto/build}# script (see +{Managing a configuration}#managing-a-configuration for details). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +At boot time, live-boot and live-config store their logfiles in +#{/var/log/live/}#. Check them for error messages. + +Additionally, to rule out other errors, it is always a good idea to tar up +your #{config/}# directory and upload it somewhere (do *{not}* send it as an +attachment to the mailing list), so that we can try to reproduce the errors +you encountered. If this is difficult (e.g. due to size) you can use the +output of #{lb config --dump}# which produces a summary of your config tree +(i.e. lists files in subdirectories of #{config/}# but does not include +them). + +Remember to send in any logs that were produced with English locale +settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or +#{LC_ALL=en_US}#. + +2~ Isolate the failing case if possible + +If possible, isolate the failing case to the smallest possible change that +breaks. It is not always easy to do this so if you cannot manage it for your +report, do not worry. However, if you plan your development cycle well, +using small enough change sets per iteration, you may be able to isolate the +problem by constructing a simpler 'base' configuration that closely matches +your actual configuration plus just the broken change set added to it. If +you have a hard time sorting out which of your changes broke, it may be that +you are including too much in each change set and should develop in smaller +increments. + +2~ Use the correct package to report the bug against + +If you do not know what component is responsible for the bug or if the bug +is a general bug concerning live systems, you can fill a bug against the +debian-live pseudo-package. + +However, we would appreciate it if you try to narrow it down according to +where the bug appears. + +3~ At build time while bootstrapping + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a +bug appears here, check if the error is related to a specific Debian package +(most likely), or if it is related to the bootstrapping tool itself. + +In both cases, this is not a bug in the live system, but rather in Debian +itself and probably we cannot fix it directly. Please report such a bug +against the bootstrapping tool or the failing package. + +3~ At build time while installing packages + +live-build installs additional packages from the Debian archive and +depending on the Debian distribution used and the daily archive state, it +can fail. If a bug appears here, check if the error is also reproducible on +a normal system. + +If this is the case, this is not a bug in the live system, but rather in +Debian - please report it against the failing package. Running +/{debootstrap}/ separately from the Live system build or running #{lb +bootstrap --debug}# will give you more information. + +Also, if you are using a local mirror and/or any sort of proxy and you are +experiencing a problem, please always reproduce it first by bootstrapping +from an official mirror. + +3~ At boot time + +If your image does not boot, please report it to the mailing list together +with the information requested in {Collect +information}#collect-information. Do not forget to mention, how/when the +image failed exactly, whether using virtualization or real hardware. If you +are using a virtualization technology of any kind, please always run it on +real hardware before reporting a bug. Providing a screenshot of the failure +is also very helpful. + +3~ At run time + +If a package was successfully installed, but fails while actually running +the Live system, this is probably a bug in the live system. However: + +2~ Do the research + +Before filing the bug, please search the web for the particular error +message or symptom you are getting. As it is highly unlikely that you are +the only person experiencing a particular problem. There is always a chance +that it has been discussed elsewhere and a possible solution, patch, or +workaround has been proposed. + +You should pay particular attention to the live systems mailing list, as +well as the homepage, as these are likely to contain the most up-to-date +information. If such information exists, always include the references to it +in your bug report. + +In addition, you should check the current bug lists for live-build, +live-boot, live-config and live-tools to see whether something similar has +already been reported. + +2~ Where to report bugs + +The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For +information on how to use the system, please see +https://bugs.debian.org/. You can also submit the bugs by using the +#{reportbug}# command from the package with the same name. + +In general, you should report build time errors against the live-build +package, boot time errors against live-boot, and run time errors against +live-config. If you are unsure of which package is appropriate or need more +help before submitting a bug report, please report it against the +debian-live pseudo-package. We will then take care about it and reassign it +where appropriate. + +Please note that bugs found in distributions derived from Debian (such as +Ubuntu and others) should *{not}* be reported to the Debian BTS unless they +can be also reproduced on a Debian system using official Debian packages. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_coding-style.ssi new file mode 100644 index 0000000..2adba20 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_coding-style.ssi @@ -0,0 +1,149 @@ +:B~ Coding Style + +1~coding-style Coding Style + +This chapter documents the coding style used in live systems. + +2~ Compatibility + +_* Don't use syntax or semantics that are unique to the Bash shell. For +example, the use of array constructs. + +_* Only use the POSIX subset - for example, use $(foo) over `foo`. + +_* You can check your scripts with 'sh -n' and 'checkbashisms'. + +_* Make sure all shell code runs with 'set -e'. + +2~ Indenting + +_* Always use tabs over spaces. + +2~ Wrapping + +_* Generally, lines are 80 chars at maximum. + +_* Use the "Linux style" of line breaks: + +Bad: + +code{ + + if foo; then + bar + fi + +}code + +Good: + +code{ + + if foo + then + bar + fi + +}code + +_* The same holds for functions: + +Bad: + +code{ + + Foo () { + bar + } + +}code + +Good: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Variables are always in capital letters. + +_* Variables used in live-build always start with #{LB_}# prefix. + +_* Internal temporary variables in live-build should start with the +#{\_LB_}# prefix. + +_* Local variables start with live-build #{\_\_LB_}# prefix. + +_* Variables in connection to a boot parameter in live-config start with +#{LIVE_}#. + +_* All other variables in live-config start with #{_}# prefix. + +_* Use braces around variables; e.g. write #{${FOO}}# instead of #{$FOO}#. + +_* Always protect variables with quotes to respect potential whitespaces: +write #{"${FOO}"}# not #{${FOO}}#. + +_* For consistency reasons, always use quotes when assigning values to +variables: + +Bad: + +code{ + + FOO=bar + +}code + +Good: + +code{ + + FOO="bar" + +}code + +_* If multiple variables are used, quote the full expression: + +Bad: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Good: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscellaneous + +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, +e.g. "#{sed -e 's|foo|bar|'}#" (without ""). + +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" +"#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test +-x /bin/foo; ...}#". + +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and +faster in execution. + +_* Use capitalized names for functions to limit messing with the users +environment. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_contributing.ssi new file mode 100644 index 0000000..30e1185 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_contributing.ssi @@ -0,0 +1,114 @@ +:B~ Contributing to the project + +1~contributing-to-project Contributing to the project + +When submitting a contribution, please clearly identify its copyright holder +and include any applicable licensing statement. Note that to be accepted, +the contribution must be licensed under the same license as the rest of the +documents, namely, GPL version 3 or later. + +Contributions to the project, such as translations and patches, are greatly +welcome. Anyone can directly commit to the repositories, however, we ask you +to send bigger changes to the mailing list to discuss them first. See the +section {Contact}#contact for more information. + +The ${project} uses Git as version control system and source code +management. As explained in {Git repositories}#git-repositories there are +two main development branches: *{debian}* and *{debian-next}*. Everybody can +commit to the debian-next branches of the live-boot, live-build, +live-config, live-images, live-manual and live-tools repositories. + +However, there are certain restrictions. The server will reject: + +_* Non fast-forward pushes. + +_* Merge commits. + +_* Adding or removing tags or branches. + +Even though all commits might be revised, we ask you to use your common +sense and make good commits with good commit messages. + +_* Write commit messages that consist of complete, meaningful sentences in +English, starting with a capital letter and ending with a full +stop. Usually, these will start with the form +"Fixing/Adding/Removing/Correcting/Translating/...". + +_* Write good commit messages. The first line must be an accurate summary of +the contents of the commit which will be included in the changelog. If you +need to make some further explanations, write them below leaving a blank +line after the first one and then another blank line after each +paragraph. Lines of paragraphs should not exceed 80 characters in length. + +_* Commit atomically, this is to say, do not mix unrelated things in the +same commit. Make one different commit for each change you make. + +2~ Aplicando Atualizações + +In order to push to the repositories, you must follow the following +procedure. Here we use live-manual as an example so replace it with the name +of the repository you want to work with. For detailed information on how to +edit live-manual see {Contributing to this document}#how-to-contribute. + +_* Obter a chave publica de commit: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Adicione a seguinte sessão na configuração do seu openssh-client: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Check out a clone of live-manual through ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Make sure you have Git author and email set: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Importante:}* Observe que você acessa quaisquer alterações no ramo *{debian-next}*. + +_* Make your changes. In this example you would first write a new section +dealing with applying patches and then prepare to commit adding the files +and writing your commit message like this: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Enviar as submissões para os servidor. + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_git.ssi new file mode 100644 index 0000000..fd15acd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_git.ssi @@ -0,0 +1,87 @@ +:B~ Git repositories + +1~git-repositories Git repositories + +The list of all the available repositories of the ${project} can be found at +http://live-systems.org/gitweb/. The project's git URLs have the form: +#{protocol://live-systems.org/git/repository}#. Thus, in order to clone +live-manual read-only, launch: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +The cloning addresses with write permission have the form: +#{git@live-systems.org:/repository}#. + +So, again, to clone live-manual over ssh you must type: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +The git tree is made up of several different branches. The *{debian}* and +the *{debian-next}* branches are particularly noteworthy because they +contain the actual work that will eventually be included in each new +release. + +After cloning any of the existing repositories, you will be on the +*{debian}* branch. This is appropriate to take a look at the state of the +project's latest release but before starting work it is crucial to switch to +the *{debian-next}* branch. To do so: + +code{ + + $ git checkout debian-next + +}code + +The *{debian-next}* branch, which is not always fast-forward, is where all +the changes are committed first before being merged into the *{debian}* +branch. To make an analogy, it is like a testing ground. If you are working +on this branch and need to pull, you will have to do a #{git pull --rebase}# +so that your local modifications are staged while pulling from the server +and then your changes will be put on top of it all. + +2~ Handling multiple repositories + +If you intend to clone several of the live systems repositories and want to +switch to the *{debian-next}* branch right away to check the latest code, +write a patch or contribute with a translation you ought to know that the +git server provides a #{mrconfig}# file to ease the handling of multiple +repositories. In order to use it you need to install the /{mr}/ package and +after that, launch: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +This command will automatically clone and checkout to the *{debian-next}* +branch the development repositories of the Debian packages produced by the +project. These include, among others, the live-images repository, which +contains the configurations used for the prebuilt images that the project +publishes for general use. For more information on how to use this +repository, see {Clone a configuration published via +Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_procedures.ssi new file mode 100644 index 0000000..f6122d3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/project_procedures.ssi @@ -0,0 +1,99 @@ +:B~ Procedures + +1~procedures Procedures + +This chapter documents the procedures within the ${project} for various +tasks that need cooperation with other teams in Debian. + +2~ Major Releases + +Releasing a new stable major version of Debian includes a lot of different +teams working together to make it happen. At some point, the Live team comes +in and builds live system images. The requirements to do this are: + +_* A mirror containing the released versions for the debian and +debian-security archives which the debian-live buildd can access. + +_* The names of the image need to be known +(e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* The data from debian-cd needs to be synced (udeb exclude lists). + +_* Images are built and mirrored on cdimage.debian.org. + +2~ Point Releases + +_* Again, we need updated mirrors of debian and debian-security. + +_* Images are built and mirrored on cdimage.debian.org. + +_* Send announcement mail. + +3~ Last Point Release of a Debian Release + +Remember to adjust both chroot and binary mirrors when building the last set +of images for a Debian release after it has been moved away from +ftp.debian.org to archive.debian.org. That way, old prebuilt live images are +still useful without user modifications. + +3~ Point release announcement template + +An announcement mail for point releases can be generated using the template +below and the following command: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Please check the mail carefully before sending and pass it to others for +proof-reading. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_basics.ssi new file mode 100644 index 0000000..063e3a9 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_basics.ssi @@ -0,0 +1,629 @@ +:B~ O básico + +1~the-basics O básico + +This chapter contains a brief overview of the build process and instructions +for using the three most commonly used image types. The most versatile image +type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or +USB portable storage device. In certain special cases, as explained later, +the #{hdd}# type may be more suitable. The chapter includes detailed +instructions for building and using a #{netboot}# type image, which is a bit +more involved due to the setup required on the server. This is an slightly +advanced topic for anyone who is not already familiar with netbooting, but +it is included here because once the setup is done, it is a very convenient +way to test and deploy images for booting on the local network without the +hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting +which is, perhaps, the easiest way of using different images for different +purposes, switching from one to the other as needed using the internet as a +means. + +Throughout the chapter, we will often refer to the default filenames +produced by live-build. If you are {downloading a prebuilt +image}#downloading-prebuilt-images instead, the actual filenames may vary. + +2~what-is-live O que é um sistema live? + +Um sistema live normalmente significa um sistema operacional inicializado em +um computador a partir de uma mídia removível, como um CD-ROM ou dispositivo +USB, ou de uma rede, pronto a usar, sem qualquer tipo de instalação na +unidade de costume (s), com a auto-configuração feita em tempo de execução +(veja {Termos}#terms). + +With live systems, it's an operating system, built for one of the supported +architectures (currently amd64 and i386). It is made from the following +parts: + +_* *{Imagem do kernel do Linux }*, normalmente chamada #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd) - Imagem do disco RAM inicial}*: um +disco de RAM configurado para a inicialização do Linux, que contém módulos +que podem ser necessários para montar a imagem do sistema e alguns scripts +para fazê-lo. + +_* *{System image}*: The operating system's filesystem image. Usually, a +SquashFS compressed filesystem is used to minimize the live system image +size. Note that it is read-only. So, during boot the live system will use a +RAM disk and 'union' mechanism to enable writing files within the running +system. However, all modifications will be lost upon shutdown unless +optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen +medium, possibly presenting a prompt or menu to allow selection of +options/configuration. It loads the Linux kernel and its initrd to run with +an associated system filesystem. Different solutions can be used, depending +on the target medium and format of the filesystem containing the previously +mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, +syslinux for HDD or USB drive booting from a VFAT partition, extlinux for +ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 +partitions, etc. + +You can use live-build to build the system image from your specifications, +set up a Linux kernel, its initrd, and a bootloader to run them, all in one +medium-dependant format (ISO9660 image, disk image, etc.). + +2~downloading-prebuilt-images Downloading prebuilt images + +While the focus of this manual is developing and building your own live +images, you may simply wish to try one of our prebuilt images, either as an +introduction to their use or instead of building your own. These images are +built using our {live-images git repository}#clone-configuration-via-git and +official stable releases are published at +https://www.debian.org/CD/live/. In addition, older and upcoming releases, +and unofficial images containing non-free firmware and drivers are available +at http://live-systems.org/cdimage/release/. + +2~using-web-builder Using the web live image builder + +As a service to the community, we run a web-based live image builder service +at http://live-systems.org/build/. This site is maintained on a best effort +basis. That is, although we strive to keep it up-to-date and operational at +all times, and do issue notices for significant operational outages, we +cannot guarantee 100% availability or fast image building, and the service +may occasionally have issues that take some time to resolve. If you have +problems or questions about the service, please {contact us}#contact, +providing us with the link to your build. + +3~ Web builder usage and caveats + +The web interface currently makes no provision to prevent the use of invalid +combinations of options, and in particular, where changing an option would +normally (i.e. using live-build directly) change defaults of other options +listed in the web form, the web builder does not change these defaults. Most +notably, if you change #{--architectures}# from the default #{i386}# to +#{amd64}#, you must change the corresponding option #{--linux-flavours}# +from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for +the version of live-build installed on the web builder for more details. The +version number of live-build is listed at the bottom of the web builder +page. + +The time estimate given by the web builder is a crude estimate only and may +not reflect how long your build actually takes. Nor is the estimate updated +once it is displayed. Please be patient. Do not refresh the page you land on +after submitting the build, as this will resubmit a new build with the same +parameters. You should {contact us}#contact if you don't receive +notification of your build only once you are certain you've waited long +enough and verified the notification e-mail did not get caught by your own +e-mail spam filter. + +The web builder is limited in the kinds of images it can build. This keeps +it simple and efficient to use and maintain. If you would like to make +customizations that are not provided for by the web interface, the rest of +this manual explains how to build your own images using live-build. + +2~building-iso-hybrid Primeiros passos: construindo uma imagem ISO híbrida + +Regardless of the image type, you will need to perform the same basic steps +to build an image each time. As a first example, create a build directory, +change to that directory and then execute the following sequence of +live-build commands to create a basic ISO hybrid image containing a default +live system without X.org. It is suitable for burning to CD or DVD media, +and also to copy onto a USB stick. + +The name of the working directory is absolutely up to you, but if you take a +look at the examples used throughout live-manual, it is a good idea to use a +name that helps you identify the image you are working with in each +directory, especially if you are working or experimenting with different +image types. In this case you are going to build a default system so let's +call it, for example, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy +in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their +various options will be used. See {The lb config command}#lb-config for more +details. + +Agora que existe a hierarquia "config/", construir a imagem com o comando +#{lb build}#: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and +your network connection. When it is complete, there should be a +#{live-image-i386.hybrid.iso}# image file, ready to use, in the current +directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Usando uma imagem live ISO hibrida + +After either building or downloading an ISO hybrid image, which can be +obtained at https://www.debian.org/CD/live/, the usual next step is to +prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or +a USB stick. + +3~burning-iso-image Queimar uma imagem ISO em um meio físico + +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the +command-line to burn the image. For instance: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copiar uma imagem ISO híbrida para um +dispositivo USB + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick +with the #{cp}# program or an equivalent. Plug in a USB stick with a size +large enough for your image file and determine which device it is, which we +hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, +such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find +the right device name by looking in #{dmesg}#'s output after plugging in the +stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# +command to copy the image to the stick. *{This will definitely overwrite +any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Using the space left on a USB stick + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first +partition on the device will be filled up by the live system. To use the +remaining free space, use a partitioning tool such as /{gparted}/ or +/{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +After the partition is created, where #{${PARTITION}}# is the name of the +partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One +possible choice would be ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-medium Booting the live medium + +The first time you boot your live medium, whether CD, DVD, USB key, or PXE +boot, some setup in your computer's BIOS may be needed first. Since BIOSes +vary greatly in features and key bindings, we cannot get into the topic in +depth here. Some BIOSes provide a key to bring up a menu of boot devices at +boot time, which is the easiest way if it is available on your +system. Otherwise, you need to enter the BIOS configuration menu and change +the boot order to place the boot device for the live system before your +normal boot device. + +Once you've booted the medium, you are presented with a boot menu. If you +just press enter here, the system will boot using the default entry, +#{Live}# and default options. For more information about boot options, see +the "help" entry in the menu and also the live-boot and live-config man +pages found within the live system. + +Assuming you've selected #{Live}# and booted a default desktop live image, +after the boot messages scroll by, you should be automatically logged into +the #{user}# account and see a desktop, ready to use. If you have booted a +console-only image, such as a #{standard}# flavour {prebuilt +image}#downloading-prebuilt-images, you should be automatically logged in on +the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Usando uma máquina virtual para testar + +It can be a great time-saver for the development of live images to run them +in a virtual machine (VM). This is not without its caveats: + +_* Running a VM requires enough RAM for both the guest OS and the host and a +CPU with hardware support for virtualization is recommended. + +_* There are some inherent limitations to running on a VM, e.g. poor video +performance, limited choice of emulated hardware. + +_* When developing for specific hardware, there is no substitute for running +on the hardware itself. + +_* Occasionally there are bugs that relate only to running in a VM. When in +doubt, test your image directly on the hardware. + +Provided you can work within these constraints, survey the available VM +software and choose one that is suitable for your needs. + +3~testing-iso-with-qemu Testing an ISO image with QEMU + +The most versatile VM in Debian is QEMU. If your processor has hardware +support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ +package description briefly lists the requirements. + +First, install /{qemu-kvm}/ if your processor supports it. If not, install +/{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in +the following examples. The /{qemu-utils}/ package is also valuable for +creating virtual disk images with #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Booting an ISO image is simple: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +See the man pages for more details. + +3~testing-iso-with-virtualbox Testing an ISO image with VirtualBox + +In order to test the ISO with /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use +#{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +In order to make the dkms package work, also the kernel headers for the +kernel flavour used in your image need to be installed. Instead of manually +listing the correct /{linux-headers}/ package in above created package list, +the selection of the right package can be done automatically by live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Building and using an HDD image + +Building an HDD image is similar to an ISO hybrid one in all respects except +you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# +which cannot be burnt to optical media. It is suitable for booting from USB +sticks, USB hard drives, and various other portable storage +devices. Normally, an ISO hybrid image can be used for this purpose instead, +but if you have a BIOS which does not handle hybrid images properly, you +need an HDD image. + +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Run the #{lb config}# command as before, except this time specifying the HDD +image type: + +code{ + + $ lb config -b hdd + +}code + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in +the current directory. + +The generated binary image contains a VFAT partition and the syslinux +bootloader, ready to be directly written on a USB device. Once again, using +an HDD image is just like using an ISO hybrid one on USB. Follow the +instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except +use the filename #{live-image-i386.img}# instead of +#{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described +above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run +#{kvm}# or #{qemu}#, depending on which version your host system needs, +specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Building a netboot image + +The following sequence of commands will create a basic netboot image +containing a default live system without X.org. It is suitable for booting +over the network. + +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean +up the necessary stages. The cause for this is that in netboot setups, a +different initramfs configuration needs to be used which live-build performs +automatically when building netboot images. Since the initramfs creation +belongs to the chroot stage, switching to netboot in an existing build +directory means to rebuild the chroot stage too. Therefore, #{lb clean}# +(which will remove the chroot stage, too) needs to be used. + +Run the #{lb config}# command as follows to configure your image for +netbooting: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +In contrast with the ISO and HDD images, netbooting does not, itself, serve +the filesystem image to the client, so the files must be served via +NFS. Different network filesystems can be chosen through lb config. The +#{--net-root-path}# and #{--net-root-server}# options specify the location +and server, respectively, of the NFS server where the filesystem image will +be located at boot time. Make sure these are set to suitable values for your +network and server. + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +In a network boot, the client runs a small piece of software which usually +resides on the EPROM of the Ethernet card. This program sends a DHCP request +to get an IP address and information about what to do next. Typically, the +next step is getting a higher level bootloader via the TFTP protocol. That +could be pxelinux, GRUB, or even boot directly to an operating system like +Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# +archive in the #{/srv/debian-live}# directory, you'll find the filesystem +image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux +bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the +DHCP server, the TFTP server and the NFS server. + +3~ Servidor DHCP + +We must configure our network's DHCP server to be sure to give an IP address +to the netbooting client system, and to advertise the location of the PXE +bootloader. + +Here is an example for inspiration, written for the ISC DHCP server +#{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ Servidor TFTP + +This serves the kernel and initial ramdisk to the system at run time. + +You should install the /{tftpd-hpa}/ package. It can serve all files +contained inside a root directory, usually #{/srv/tftp}#. To let it serve +files inside #{/srv/debian-live/tftpboot}#, run as root the following +command: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +and fill in the new tftp server directory when being asked about it. + +3~ Servidor NFS + +Once the guest computer has downloaded and booted a Linux kernel and loaded +its initrd, it will try to mount the Live filesystem image through a NFS +server. + +You need to install the /{nfs-kernel-server}/ package. + +Then, make the filesystem image available through NFS by adding a line like +the following to #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +and tell the NFS server about this new export with the following command: + +code{ + + # exportfs -rv + +}code + +Setting up these three services can be a little tricky. You might need some +patience to get all of them working together. For more information, see the +syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the +Debian Installer Manual's TFTP Net Booting section at +http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, +as their processes are very similar. + +3~ Netboot testing HowTo + +Netboot image creation is made easy with live-build, but testing the images +on physical machines can be really time consuming. + +To make our life easier, we can use virtualization. + +3~ Qemu + +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Edit #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Senha para $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executando /etc/qemu-ifup" + echo "Levando o $1 para o modo bridged..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adicionando $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Get, or build a #{grub-floppy-netboot}#. + +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using +the internet as a means. The requirements for webbooting are very few. On +the one hand, you need a medium with a bootloader, an initial ramdisk and a +kernel. On the other hand, a web server to store the squashfs files which +contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which +are available on the project's homepage at http://live-systems.org/. Using +prebuilt images would be handy for doing initial testing until one can fine +tune their own needs. If you have built a live image you will find the files +needed for webbooting in the build directory under #{binary/live/}#. The +files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso +image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific +case, it would be #{/mnt/live/}#. This method has the disadvantage that you +need to be root to be able to mount the image. However, it has the advantage +that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image +and uploading it to the web server at the same time, is using the midnight +commander or /{mc}/. If you have the /{genisoimage}/ package installed, the +two-pane file manager allows you to browse the contents of an iso file in +one pane and upload the files via ftp in the other pane. Even though this +method requires manual work, it does not require root privileges. + +3~ Booting webboot images + +While some users will prefer virtualization to test webbooting, we refer to +real hardware here to match the following possible use case which should +only be considered as an example. + +In order to boot a webboot image it is enough to have the components +mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a +directory named #{live/}# and install syslinux as bootloader. Then boot from +the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot +options. live-boot will retrieve the squashfs file and store it into +ram. This way, it is possible to use the downloaded compressed filesystem as +a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-binary.ssi new file mode 100644 index 0000000..aa7929a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-binary.ssi @@ -0,0 +1,62 @@ +:B~ Customizing the binary image + +1~customizing-binary Customizing the binary image + +2~ Bootloaders + +live-build uses /{syslinux}/ and some of its derivatives (depending on the +image type) as bootloaders by default. They can be easily customized to suit +your needs. + +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# +into #{config/bootloaders}# and edit the files in there. If you do not want +to bother modifying all supported bootloader configurations, only providing +a local customized copy of one of the bootloaders, e.g. *{isolinux}* in +#{config/bootloaders/isolinux}# is enough too, depending on your use case. + +When modifying one of the default themes, if you want to use a personalized +background image that will be displayed together with the boot menu, add a +splash.png picture of 640x480 pixels. Then, remove the splash.svg file. + +There are many possibilities when it comes to making changes. For instance, +syslinux derivatives are configured by default with a timeout of 0 (zero) +which means that they will pause indefinitely at their splash screen until +you press a key. + +To modify the boot timeout of a default #{iso-hybrid}# image just edit a +default *{isolinux.cfg}* file specifying the timeout in units of 1/10 +seconds. A modified *{isolinux.cfg}* to boot after five seconds would be +similar to this: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ ISO metadata + +When creating an ISO9660 binary image, you can use the following options to +add various textual metadata for your image. This can help you easily +identify the version or configuration of an image without booting it. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the +application that will be on the image. The maximum length for this field is +128 characters. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the +preparer of the image, usually with some contact details. The default for +this option is the live-build version you are using, which may help with +debugging later. The maximum length for this field is 128 characters. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the +publisher of the image, usually with some contact details. The maximum +length for this field is 128 characters. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of +the image. This is used as a user-visible label on some platforms such as +Windows and Apple Mac OS. The maximum length for this field is 32 +characters. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-contents.ssi new file mode 100644 index 0000000..fac28c3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-contents.ssi @@ -0,0 +1,135 @@ +:B~ Personalizando conteúdo + +1~customizing-contents Customizing contents + +This chapter discusses fine-tuning customization of the live system contents +beyond merely choosing which packages to include. Includes allow you to add +or replace arbitrary files in your live system image, hooks allow you to +execute arbitrary commands at different stages of the build and at boot +time, and preseeding allows you to configure packages when they are +installed by supplying answers to debconf questions. + +2~includes Includes + +While ideally a live system would include files entirely provided by +unmodified packages, it is sometimes convenient to provide or modify some +content by means of files. Using includes, it is possible to add (or +replace) arbitrary files in your live system image. live-build provides two +mechanisms for using them: + +_* Chroot local includes: These allow you to add or replace files to the +chroot/Live filesystem. Please see {Live/chroot local +includes}#live-chroot-local-includes for more information. + +_* Binary local includes: These allow you to add or replace files in the +binary image. Please see {Binary local includes}#binary-local-includes for +more information. + +Please see {Terms}#terms for more information about the distinction between +the "Live" and "binary" images. + +3~live-chroot-local-includes Live/chroot local includes + +Chroot local includes can be used to add or replace files in the chroot/Live +filesystem so that they may be used in the Live system. A typical use is to +populate the skeleton user directory (#{/etc/skel}#) used by the Live system +to create the live user's home directory. Another is to supply configuration +files that can be simply added or replaced in the image without processing; +see {Live/chroot local hooks}#live-chroot-local-hooks if processing is +needed. + +To include files, simply add them to your #{config/includes.chroot}# +directory. This directory corresponds to the root directory #{/}# of the +live system. For example, to add a file #{/var/www/index.html}# in the live +system, use: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Your configuration will then have the following layout: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Chroot local includes are installed after package installation so that files +installed by packages are overwritten. + +3~binary-local-includes Binary local includes + +To include material such as documentation or videos on the medium filesystem +so that it is accessible immediately upon insertion of the medium without +booting the Live system, you can use binary local includes. This works in a +similar fashion to chroot local includes. For example, suppose the files +#{~/video_demo.*}# are demo videos of the live system described by and +linked to by an HTML index page. Simply copy the material to +#{config/includes.binary/}# as follows: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +These files will now appear in the root directory of the live medium. + +2~hooks Hooks + +Hooks allow commands to be performed in the chroot and binary stages of the +build in order to customize the image. + +3~live-chroot-local-hooks Live/chroot local hooks + +To run commands in the chroot stage, create a hook script with a +#{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run in the chroot after the rest of your chroot +configuration has been applied, so remember to ensure your configuration +includes all packages and files your hook needs in order to run. See the +example chroot hook scripts for various common chroot customization tasks +provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy +or symlink to use them in your own configuration. + +3~boot-time-hooks Boot-time hooks + +To execute commands at boot time, you can supply live-config hooks as +explained in the "Customization" section of its man page. Examine +live-config's own hooks provided in #{/lib/live/config/}#, noting the +sequence numbers. Then provide your own hook prefixed with an appropriate +sequence number, either as a chroot local include in +#{config/includes.chroot/lib/live/config/}#, or as a custom package as +discussed in {Installing modified or third-party +packages}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +To run commands in the binary stage, create a hook script with a +#{.hook.binary}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run after all other binary commands are run, but +before binary_checksums, the very last binary command. The commands in your +hook do not run in the chroot, so take care to not modify any files outside +of the build tree, or you may damage your build system! See the example +binary hook scripts for various common binary customization tasks provided +in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or +symlink to use them in your own configuration. + +2~ Preseeding Debconf questions + +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed +by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf +preseed files and are installed by live-build using +#{debconf-set-selections}# during the corresponding stage. + +For more information about debconf, please see #{debconf(7)}# in the +/{debconf}/ package. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-installer.ssi new file mode 100644 index 0000000..2f3a5a2 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-installer.ssi @@ -0,0 +1,86 @@ +:B~ Customizing Debian Installer + +1~customizing-installer Customizing Debian Installer + +Live system images can be integrated with Debian Installer. There are a +number of different types of installation, varying in what is included and +how the installer operates. + +Please note the careful use of capital letters when referring to the "Debian +Installer" in this section - when used like this we refer explicitly to the +official installer for the Debian system, not anything else. It is often +seen abbreviated to "d-i". + +2~ Types of Debian Installer + +The three main types of installer are: + +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". + +On such images, Debian is installed by fetching and installing .deb packages +using /{debootstrap}/, from local media or some network-based network, +resulting in a default Debian system being installed to the hard disk. + +This whole process can be preseeded and customized in a number of ways; see +the relevant pages in the Debian Installer manual for more information. Once +you have a working preseeding file, live-build can automatically put it in +the image and enable it for you. + +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. + +Installation will proceed in an identical fashion to the "normal" +installation described above, but at the actual package installation stage, +instead of using /{debootstrap}/ to fetch and install packages, the live +filesystem image is copied to the target. This is achieved with a special +udeb called live-installer. + +After this stage, the Debian Installer continues as normal, installing and +configuring items such as bootloaders and local users, etc. + +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. + +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. + +Note that by default, live-build does not include Debian Installer images in +the images, it needs to be specifically enabled with #{lb config}#. Also, +please note that for the "Desktop" installer to work, the kernel of the live +system must match the kernel #{d-i}# uses for the specified +architecture. For example: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Customizing Debian Installer by preseeding + +As described in the Debian Installer Manual, Appendix B at +https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a +way to set answers to questions asked during the installation process, +without having to manually enter the answers while the installation is +running. This makes it possible to fully automate most types of installation +and even offers some features not available during normal installations." +This kind of customization is best accomplished with live-build by placing +the configuration in a #{preseed.cfg}# file included in +#{config/includes.installer/}#. For example, to preseed setting the locale +to #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Customizing Debian Installer content + +For experimental or debugging purposes, you might want to include locally +built #{d-i}# component udeb packages. Place these in +#{config/packages.binary/}# to include them in the image. Additional or +replacement files and directories may be included in the installer initrd as +well, in a similar fashion to {Live/chroot local +includes}#live-chroot-local-includes, by placing the material in +#{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-overview.ssi new file mode 100644 index 0000000..2a6de97 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-overview.ssi @@ -0,0 +1,77 @@ +:B~ Personalizando conteúdo + +1~customization-overview Visão geral sobre personalização + +This chapter gives an overview of the various ways in which you may +customize a live system. + +2~ Configuração de tempo de construção X tempo de inicialização + +As opções de configuração do sistema Live são divididas em opções de tempo +de compilação que são as opções aplicadas em tempo de compilação e opções de +tempo de inicialização que são aplicadas em tempo de inicialização. Opções +de inicialização são divididas naquelas que ocorrem em início do +inicialização, aplicadas pelo pacote live-boot e aquelas que acontecem no +final da inicialização, aplicadas pelo live-config. Qualquer opção de +inicialização pode ser modificada pelo usuário, especificando a no prompt de +inicialização. A imagem também pode ser construída com os parâmetros de +inicialização padrão para que os usuários possam normalmente apenas +inicializar diretamente pelo sistema live, sem especificar quaisquer opções +quando todos os padrões são adequados. Em particular, o argumento para #{lb +--bootappend-live}# consiste de quaisquer opções padrão de kernel de linha +de comando para o sistema live, tais como persistência, layouts de teclado, +ou fuso horário. Veja {Personalizando local e +linguagem}#customizing-locale-and-language, por exemplo. + +Build-time configuration options are described in the #{lb config}# man +page. Boot-time options are described in the man pages for live-boot and +live-config. Although the live-boot and live-config packages are installed +within the live system you are building, it is recommended that you also +install them on your build system for easy reference when you are working on +your configuration. It is safe to do so, as none of the scripts contained +within them are executed unless the system is configured as a live system. + +2~stages-of-the-build Etapas da construção + +The build process is divided into stages, with various customizations +applied in sequence in each. The first stage to run is the *{bootstrap}* +stage. This is the initial phase of populating the chroot directory with +packages to make a barebones Debian system. This is followed by the +*{chroot}* stage, which completes the construction of chroot directory, +populating it with all of the packages listed in the configuration, along +with any other materials. Most customization of content occurs in this +stage. The final stage of preparing the live image is the *{binary}* stage, +which builds a bootable image, using the contents of the chroot directory to +construct the root filesystem for the Live system, and including the +installer and any other additional material on the target medium outside of +the Live system's filesystem. After the live image is built, if enabled, the +source tarball is built in the *{source}* stage. + +Within each of these stages, there is a particular sequence in which +commands are applied. These are arranged in such a way as to ensure +customizations can be layered in a reasonable fashion. For example, within +the *{chroot}* stage, preseeds are applied before any packages are +installed, packages are installed before any locally included files are +copied, and hooks are run later, after all of the materials are in place. + +2~ Complementar lb config com arquivos + +Although #{lb config}# creates a skeletal configuration in the #{config/}# +directory, to accomplish your goals, you may need to provide additional +files in subdirectories of #{config/}#. Depending on where the files are +stored in the configuration, they may be copied into the live system's +filesystem or into the binary image filesystem, or may provide build-time +configurations of the system that would be cumbersome to pass as +command-line options. You may include things such as custom lists of +packages, custom artwork, or hook scripts to run either at build time or at +boot time, boosting the already considerable flexibility of debian-live with +code of your own. + +2~ Tarefas de personalização + +Os capítulos seguintes são organizados pelos tipos de personalização de +tarefas que os usuários normalmente executam: {Personalizar a instalação de +pacote}#customizing-package-installation, {Personalizar +conteúdos}#customizing-package-installation, e {Personalizar localizade e +linguagem}#customizing-locale-and-language cobrem apenas algumas das coisas +que você pode querer fazer. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-packages.ssi new file mode 100644 index 0000000..dd6bd88 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-packages.ssi @@ -0,0 +1,643 @@ +:B~ Customizing package installation + +1~customizing-package-installation Customizing package installation + +Perhaps the most basic customization of a live system is the selection of +packages to be included in the image. This chapter guides you through the +various build-time options to customize live-build's installation of +packages. The broadest choices influencing which packages are available to +install in the image are the distribution and archive areas. To ensure +decent download speeds, you should choose a nearby distribution mirror. You +can also add your own repositories for backports, experimental or custom +packages, or include packages directly as files. You can define lists of +packages, including metapackages which will install many related packages at +once, such as packages for a particular desktop or language. Finally, a +number of options give some control over /{apt}/, or if you prefer, +/{aptitude}/, at build time when packages are installed. You may find these +handy if you use a proxy, want to disable installation of recommended +packages to save space, or need to control which versions of packages are +installed via APT pinning, to name a few possibilities. + +2~ Package sources + +3~ Distribution, archive areas and mode + +The distribution you choose has the broadest impact on which packages are +available to include in your live image. Specify the codename, which +defaults to ${testing} for the ${testing} version of live-build. Any current +distribution carried in the archive may be specified by its codename +here. (See {Terms}#terms for more details.) The #{--distribution}# option +not only influences the source of packages within the archive, but also +instructs live-build to behave as needed to build each supported +distribution. For example, to build against the *{unstable}* release, sid, +specify: + +code{ + + $ lb config --distribution sid + +}code + +Within the distribution archive, archive areas are major divisions of the +archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only +#{main}# contains software that is part of the Debian distribution, hence +that is the default. One or more values may be specified, e.g. + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimental support is available for some Debian derivatives through a +#{--mode}# option. By default, this option is set to #{debian}# only if you +are building on a Debian or on an unknown system. If #{lb config}# is +invoked on any of the supported derivatives, it will default to create an +image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, +the distribution names and archive areas for the specified derivative are +supported instead of the ones for Debian. The mode also modifies live-build +behaviour to suit the derivatives. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Distribution mirrors + +The Debian archive is replicated across a large network of mirrors around +the world so that people in each region can choose a nearby mirror for best +download speed. Each of the #{--mirror-*}# options governs which +distribution mirror is used at various stages of the build. Recall from +{Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is +when the chroot is initially populated by /{debootstrap}/ with a minimal +system, and the *{chroot}* stage is when the chroot used to construct the +live system's filesystem is built. Thus, the corresponding mirror switches +are used for those stages, and later, in the *{binary}* stage, the +#{--mirror-binary}# and #{--mirror-binary-security}# values are used, +superseding any mirrors used in an earlier stage. + +3~distribution-mirrors-build-time Distribution mirrors used at build time + +To set the distribution mirrors used at build time to point at a local +mirror, it is sufficient to set #{--mirror-bootstrap}# and +#{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the +#{--mirror-bootstrap}# value. + +3~ Distribution mirrors used at run time + +The #{--mirror-binary*}# options govern the distribution mirrors placed in +the binary image. These may be used to install additional packages while +running the live system. The defaults employ #{httpredir.debian.org}#, a +service that chooses a geographically close mirror based, among other +things, on the user's IP family and the availability of the mirrors. This is +a suitable choice when you cannot predict which mirror will be best for all +of your users. Or you may specify your own values as shown in the example +below. An image built from this configuration would only be suitable for +users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Additional repositories + +You may add more repositories, broadening your package choices beyond what +is available in your target distribution. These may be, for example, for +backports, experimental or custom packages. To configure additional +repositories, create #{config/archives/your-repository.list.chroot}#, and/or +#{config/archives/your-repository.list.binary}# files. As with the +#{--mirror-*}# options, these govern the repositories used in the *{chroot}* +stage when building the image, and in the *{binary}* stage, i.e. for use +when running the live system. + +For example, #{config/archives/live.list.chroot}# allows you to install +packages from the debian-live snapshot repository at live system build time. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +If you add the same line to #{config/archives/live.list.binary}#, the +repository will be added to your live system's #{/etc/apt/sources.list.d/}# +directory. + +If such files exist, they will be picked up automatically. + +You should also put the GPG key used to sign the repository into +#{config/archives/your-repository.key.{binary,chroot}}# files. + +Should you need custom APT pinning, such APT preferences snippets can be +placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and +will be automatically added to your live system's +#{/etc/apt/preferences.d/}# directory. + +2~choosing-packages-to-install Choosing packages to install + +There are a number of ways to choose which packages live-build will install +in your image, covering a variety of different needs. You can simply name +individual packages to install in a package list. You can also use +metapackages in those lists, or select them using package control file +fields. And finally, you may place package files in your #{config/}# tree, +which is well suited to testing of new or experimental packages before they +are available from a repository. + +3~package-lists Package lists + +Package lists are a powerful way of expressing which packages should be +installed. The list syntax supports conditional sections which makes it easy +to build lists and adapt them for use in multiple configurations. Package +names may also be injected into the list using shell helpers at build time. + +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. + +3~using-metapackages Using metapackages + +The simplest way to populate your package list is to use a task metapackage +maintained by your distribution. For example: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# +2.x. Unlike predefined lists, task metapackages are not specific to the Live +System project. Instead, they are maintained by specialist working groups +within the distribution and therefore reflect the consensus of each group +about which packages best serve the needs of the intended users. They also +cover a much broader range of use cases than the predefined lists they +replace. + +All task metapackages are prefixed #{task-}#, so a quick way to determine +which are available (though it may contain a handful of false hits that +match the name but aren't metapackages) is to match on the package name +with: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +In addition to these, you will find other metapackages with various +purposes. Some are subsets of broader task packages, like #{gnome-core}#, +while others are individual specialized parts of a Debian Pure Blend, such +as the #{education-*}# metapackages. To list all metapackages in the +archive, install the #{debtags}# package and list all packages with the +#{role::metapackage}# tag as follows: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Local package lists + +Whether you list metapackages, individual packages, or a combination of +both, all local package lists are stored in #{config/package-lists/}#. Since +more than one list can be used, this lends itself well to modular +designs. For example, you may decide to devote one list to a particular +choice of desktop, another to a collection of related packages that might as +easily be used on top of a different desktop. This allows you to experiment +with different combinations of sets of packages with a minimum of fuss, +sharing common lists between different live image projects. + +Package lists that exist in this directory need to have a #{.list}# suffix +in order to be processed, and then an additional stage suffix, #{.chroot}# +or #{.binary}# to indicate which stage the list is for. + +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. + +3~ Local binary package lists + +To make a binary stage list, place a file suffixed with #{.list.binary}# in +#{config/package-lists/}#. These packages are not installed in the live +filesystem, but are included on the live medium under #{pool/}#. You would +typically use such a list with one of the non-live installer variants. As +mentioned above, if you want this list to be the same as your chroot stage +list, simply use the #{.list}# suffix by itself. + +3~generated-package-lists Generated package lists + +It sometimes happens that the best way to compose a list is to generate it +with a script. Any line starting with an exclamation point indicates a +command to be executed within the chroot when the image is built. For +example, one might include the line #{! grep-aptavail -n -sPackage +-FPriority standard | sort}# in a package list to produce a sorted list of +available packages with #{Priority: standard}#. + +In fact, selecting packages with the #{grep-aptavail}# command (from the +#{dctrl-tools}# package) is so useful that #{live-build}# provides a +#{Packages}# helper script as a convenience. This script takes two +arguments: #{field}# and #{pattern}#. Thus, you can create a list with the +following contents: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Using conditionals inside package lists + +Any of the live-build configuration variables stored in #{config/*}# (minus +the #{LB_}# prefix) may be used in conditional statements in package +lists. Generally, this means any #{lb config}# option uppercased and with +dashes changed to underscores. But in practice, it is only the ones that +influence package selection that make sense, such as #{DISTRIBUTION}#, +#{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. + +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is +specified: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +You may test for any one of a number of values, e.g. to install +/{memtest86+}/ if either #{--architectures i386}# or #{--architectures +amd64}# is specified: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +You may also test against variables that may contain more than one value, +e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified +via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +The nesting of conditionals is not supported. + +% FIXME: + +3~ Removing packages at install time + +You can list packages in files with #{.list.chroot_live}# and +#{.list.chroot_install}# suffixes inside the #{config/package-lists}# +directory. If both a live and an install list exist, the packages in the +#{.list.chroot_live}# list are removed with a hook after the installation +(if the user uses the installer). The packages in the +#{.list.chroot_install}# list are present both in the live system and in the +installed system. This is a special tweak for the installer and may be +useful if you have #{--debian-installer live}# set in your config, and wish +to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Desktop and language tasks + +Desktop and language tasks are special cases that need some extra planning +and configuration. Live images are different from Debian Installer images in +this respect. In the Debian Installer, if the medium was prepared for a +particular desktop environment flavour, the corresponding task will be +automatically installed. Thus, there are internal #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which +are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for +tasks for languages, but the user's language choice during the install +influences the selection of corresponding language tasks. + +When developing a desktop live image, the image typically boots directly to +a working desktop, the choices of both desktop and default language having +been made at build time, not at run time as in the case of the Debian +Installer. That's not to say that a live image couldn't be built to support +multiple desktops or multiple languages and offer the user a choice, but +that is not live-build's default behaviour. + +Because there is no provision made automatically for language tasks, which +include such things as language-specific fonts and input-method packages, if +you want them, you need to specify them in your configuration. For example, +a GNOME desktop image containing support for German might include these task +metapackages: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Kernel flavour and version + +One or more kernel flavours will be included in your image by default, +depending on the architecture. You can choose different flavours via the +#{--linux-flavours}# option. Each flavour is suffixed to the default stub +#{linux-image}# to form each metapackage name which in turn depends on an +exact kernel package to be included in your image. + +Thus by default, an #{amd64}# architecture image will include the +#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture +image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured +archives, you can specify a different kernel package name stub with the +#{--linux-packages}# option. For example, supposing you are building an +#{amd64}# architecture image and add the experimental archive for testing +purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# +kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Custom kernels + +You can build and include your own custom kernels, so long as they are +integrated within the Debian package management system. The live-build +system does not support kernels not built as #{.deb}# packages. + +The proper and recommended way to deploy your own kernel packages is to +follow the instructions in the #{kernel-handbook}#. Remember to modify the +ABI and flavour suffixes appropriately, then include a complete build of the +#{linux}# and matching #{linux-latest}# packages in your repository. + +If you opt to build the kernel packages without the matching metapackages, +you need to specify an appropriate #{--linux-packages}# stub as discussed in +{Kernel flavour and version}#kernel-flavour-and-version. As we explain in +{Installing modified or third-party +packages}#installing-modified-or-third-party-packages, it is best if you +include your custom kernel packages in your own repository, though the +alternatives discussed in that section work as well. + +It is beyond the scope of this document to give advice on how to customize +your kernel. However, you must at least ensure your configuration satisfies +these minimum requirements: + +_* Use an initial ramdisk. + +_* Include the union filesystem module (i.e. usually #{aufs}#). + +_* Include any other filesystem modules required by your configuration +(i.e. usually #{squashfs}#). + +2~installing-modified-or-third-party-packages Installing modified or +third-party packages + +While it is against the philosophy of a live system, it may sometimes be +necessary to build a live system with modified versions of packages that are +in the Debian repository. This may be to modify or support additional +features, languages and branding, or even to remove elements of existing +packages that are undesirable. Similarly, "third-party" packages may be used +to add bespoke and/or proprietary functionality. + +This section does not cover advice regarding building or maintaining +modified packages. Joachim Breitner's 'How to fork privately' method from +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +may be of interest, however. The creation of bespoke packages is covered in +the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ +and elsewhere. + +There are two ways of installing modified custom packages: + +_* #{packages.chroot}# + +_* Using a custom APT repository + +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" +customizations but has a number of drawbacks, while using a custom APT +repository is more time-consuming to set up. + +3~ Using #{packages.chroot}# to install custom packages + +To install a custom package, simply copy it to the +#{config/packages.chroot/}# directory. Packages that are inside this +directory will be automatically installed into the live system during build +- you do not need to specify them elsewhere. + +Packages *{must}* be named in the prescribed way. One simple way to do this +is to use #{dpkg-name}#. + +Using #{packages.chroot}# for installation of custom packages has +disadvantages: + +_* It is not possible to use secure APT. + +_* You must install all appropriate packages in the +#{config/packages.chroot/}# directory. + +_* It does not lend itself to storing live system configurations in revision +control. + +3~ Using an APT repository to install custom packages + +Unlike using #{packages.chroot}#, when using a custom APT repository you +must ensure that you specify the packages elsewhere. See {Choosing packages +to install}#choosing-packages-to-install for details. + +While it may seem unnecessary effort to create an APT repository to install +custom packages, the infrastructure can be easily re-used at a later date to +offer updates of the modified packages. + +3~ Custom packages and APT + +live-build uses APT to install all packages into the live system so will +therefore inherit behaviours from this program. One relevant example is that +(assuming a default configuration) given a package available in two +different repositories with different version numbers, APT will elect to +install the package with the higher version number. + +Because of this, you may wish to increment the version number in your custom +packages' #{debian/changelog}# files to ensure that your modified version is +installed over one in the official Debian repositories. This may also be +achieved by altering the live system's APT pinning preferences - see {APT +pinning}#apt-pinning for more information. + +2~ Configuring APT at build time + +You can configure APT through a number of options applied only at build +time. (APT configuration used in the running live system may be configured +in the normal way for live system contents, that is, by including the +appropriate configurations through #{config/includes.chroot/}#.) For a +complete list, look for options starting with #{apt}# in the #{lb_config}# +man page. + +3~choosing-apt-or-aptitude Choosing apt or aptitude + +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages +at build time. Which utility is used is governed by the #{--apt}# argument +to #{lb config}#. Choose the method implementing the preferred behaviour for +package installation, the notable difference being how missing packages are +handled. + +_* #{apt}#: With this method, if a missing package is specified, the package +installation will fail. This is the default setting. + +_* #{aptitude}#: With this method, if a missing package is specified, the +package installation will succeed. + +3~ Using a proxy with APT + +One commonly required APT configuration is to deal with building an image +behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# +or #{--apt-http-proxy}# options as needed, e.g. + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Tweaking APT to save space + +You may find yourself needing to save some space on the image medium, in +which case one or the other or both of the following options may be of +interest. + +If you don't want to include APT indices in the image, you can omit those +with: + +code{ + + $ lb config --apt-indices false + +}code + +This will not influence the entries in #{/etc/apt/sources.list}#, but merely +whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is +that APT needs those indices in order to operate in the live system, so +before performing #{apt-cache search}# or #{apt-get install}#, for instance, +the user must #{apt-get update}# first to create those indices. + +If you find the installation of recommended packages bloats your image too +much, provided you are prepared to deal with the consequences discussed +below, you may disable that default option of APT with: + +code{ + + $ lb config --apt-recommends false + +}code + +The most important consequence of turning off recommends is that +#{live-boot}# and #{live-config}# themselves recommend some packages that +provide important functionality used by most Live configurations, such as +#{user-setup}# which #{live-config}# recommends and is used to create the +live user. In all but the most exceptional circumstances you need to add +back at least some of these recommends to your package lists or else your +image will not work as expected, if at all. Look at the recommended packages +for each of the #{live-*}# packages included in your build and if you are +not certain you can omit them, add them back into your package lists. + +The more general consequence is that if you don't install recommended +packages for any given package, that is, "packages that would be found +together with this one in all but unusual installations" (Debian Policy +Manual, section 7.2), some packages that users of your Live system actually +need may be omitted. Therefore, we suggest you review the difference turning +off recommends makes to your packages list (see the #{binary.packages}# file +generated by #{lb build}#) and re-include in your list any missing packages +that you still want installed. Alternatively, if you find you only want a +small number of recommended packages left out, leave recommends enabled and +set a negative APT pin priority on selected packages to prevent them from +being installed, as explained in {APT pinning}#apt-pinning. + +3~ Passing options to apt or aptitude + +If there is not a #{lb config}# option to alter APT's behaviour in the way +you need, use #{--apt-options}# or #{--aptitude-options}# to pass any +options through to your configured APT tool. See the man pages for #{apt}# +and #{aptitude}# for details. Note that both options have default values +that you will need to retain in addition to any overrides you may +provide. So, for example, suppose you have included something from +#{snapshot.debian.org}# for testing purposes and want to specify +#{Acquire::Check-Valid-Until=false}# to make APT happy with the stale +#{Release}# file, you would do so as per the following example, appending +the new option after the default value #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Please check the man pages to fully understand these options and when to use +them. This is an example only and should not be construed as advice to +configure your image this way. This option would not be appropriate for, +say, a final release of a live image. + +For more complicated APT configurations involving #{apt.conf}# options you +might want to create a #{config/apt/apt.conf}# file instead. See also the +other #{apt-*}# options for a few convenient shortcuts for frequently needed +options. + +3~apt-pinning APT pinning + +For background, please first read the #{apt_preferences(5)}# man page. APT +pinning can be configured either for build time, or else for run time. For +the former, create #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the +latter, create #{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live +packages that end up in the binary image to be installed from sid at build +time. You need to add sid to your APT sources and pin the live packages from +it higher, but all other packages from it lower, than the default +priority. Thus, only the packages you want are installed from sid at build +time and all others are taken from the target system distribution, +${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Negative pin priorities will prevent a package from being installed, as in +the case where you do not want a package that is recommended by another +package. Suppose you are building an LXDE image using #{task-lxde-desktop}# +in #{config/package-lists/desktop.list.chroot}#, but don't want the user +prompted to store wifi passwords in the keyring. This metapackage depends on +/{lxde-core}/, which recommends /{gksu}/, which in turn recommends +/{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ +package. This can be done by adding the following stanza to +#{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-runtime.ssi new file mode 100644 index 0000000..3e44cb3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_customization-runtime.ssi @@ -0,0 +1,441 @@ +:B~ Customizing run time behaviours + +1~customizing-run-time-behaviours Customizing run time behaviours + +All configuration that is done during run time is done by live-config. Here +are some of the most common options of live-config that users are interested +in. A full list of all possibilities can be found in the man page of +live-config. + +2~ Customizing the live user + +One important consideration is that the live user is created by live-boot at +boot time, not by live-build at build time. This not only influences where +materials relating to the live user are introduced in your build, as +discussed in {Live/chroot local includes}#live-chroot-local-includes, but +also any groups and permissions associated with the live user. + +You can specify additional groups that the live user will belong to by using +any of the possibilities to configure live-config. For example, to add the +live user to the #{fuse}# group, you can either add the following file in +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +or use +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +as a boot parameter. + +It is also possible to change the default username "user" and the default +password "live". If you want to do that for any reason, you can easily +achieve it as follows: + +To change the default username you can simply specify it in your config: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +One possible way of changing the default password is by means of a hook as +described in {Boot-time hooks}#boot-time-hooks. In order to do that you can +use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, +prefix it accordingly (e.g. 2000-passwd) and add it to +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Customizing locale and language + +When the live system boots, language is involved in two steps: + +_* the locale generation + +_* setting the keyboard configuration + +The default locale when building a Live system is +#{locales=en_US.UTF-8}#. To define the locale that should be generated, use +the #{locales}# parameter in the #{--bootappend-live}# option of #{lb +config}#, e.g. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Multiple locales may be specified as a comma-delimited list. + +This parameter, as well as the keyboard configuration parameters indicated +below, can also be used at the kernel command line. You can specify a locale +by #{language_country}# (in which case the default encoding is used) or the +full #{language_country.encoding}# word. A list of supported locales and the +encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. + +Both the console and X keyboard configuration are performed by +#{live-config}# using the #{console-setup}# package. To configure them, use +the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and +#{keyboard-model}# boot parameters via the #{--bootappend-live}# +option. Valid options for these can be found in +#{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a +given language, try searching for the English name of the language and/or +the country where the language is spoken, e.g: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Note that each variant lists the layout to which it applies in the +description. + +Often, only the layout needs to be configured. For example, to get the +locale files for German and Swiss German keyboard layout in X use: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +However, for very specific use cases, you may wish to include other +parameters. For example, to set up a French system with a French-Dvorak +layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Multiple values may be specified as comma-delimited lists for each of the +#{keyboard-*}# options, with the exception of #{keyboard-model}#, which +accepts only one value. Please see the #{keyboard(5)}# man page for details +and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and +#{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are +given, they will be matched one-to-one with #{keyboard-layouts}# values (see +#{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to +define two layouts, the default being US QWERTY and the other being US +Dvorak, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistence + +A live cd paradigm is a pre-installed system which runs from read-only +media, like a cdrom, where writes and modifications do not survive reboots +of the host hardware which runs it. + +A live system is a generalization of this paradigm and thus supports other +media in addition to CDs; but still, in its default behaviour, it should be +considered read-only and all the run-time evolutions of the system are lost +at shutdown. + +'Persistence' is a common name for different kinds of solutions for saving +across reboots some, or all, of this run-time evolution of the system. To +understand how it works it would be handy to know that even if the system is +booted and run from read-only media, modifications to the files and +directories are written on writable media, typically a ram disk (tmpfs) and +ram disks' data do not survive reboots. + +The data stored on this ramdisk should be saved on a writable persistent +medium like local storage media, a network share or even a session of a +multisession (re)writable CD/DVD. All these media are supported in live +systems in different ways, and all but the last one require a special boot +parameter to be specified at boot time: #{persistence}#. + +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not +set), local storage media (e.g. hard disks, USB drives) will be probed for +persistence volumes during boot. It is possible to restrict which types of +persistence volumes to use by specifying certain boot parameters described +in the live-boot(7) man page. A persistence volume is any of the following: + +_* a partition, identified by its GPT name. + +_* a filesystem, identified by its filesystem label. + +_* an image file located on the root of any readable filesystem (even an +NTFS partition of a foreign OS), identified by its filename. + +The volume label for overlays must be #{persistence}# but it will be ignored +unless it contains in its root a file named #{persistence.conf}# which is +used to fully customize the volume's persistence, this is to say, specifying +the directories that you want to save in your persistence volume after a +reboot. See {The persistence.conf file}#persistence-conf for more details. + +Here are some examples of how to prepare a volume to be used for +persistence. It can be, for instance, an ext4 partition on a hard disk or on +a usb key created with, e.g.: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +See also {Using the space left on a USB stick}#using-usb-extra-space. + +If you already have a partition on your device, you could just change the +label with one of the following: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Here's an example of how to create an ext4-based image file to be used for +persistence: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Once the image file is created, as an example, to make #{/usr}# persistent +but only saving the changes you make to that directory and not all the +contents of #{/usr}#, you can use the "union" option. If the image file is +located in your home directory, copy it to the root of your hard drive's +filesystem and mount it in #{/mnt}# as follows: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Then, create the #{persistence.conf}# file adding content and unmount the +image file. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Now, reboot into your live medium with the boot parameter "persistence". + +3~persistence-conf The persistence.conf file + +A volume with the label #{persistence}# must be configured by means of the +#{persistence.conf}# file to make arbitrary directories persistent. That +file, located on the volume's filesystem root, controls which directories it +makes persistent, and in which way. + +How custom overlay mounts are configured is described in full detail in the +persistence.conf(5) man page, but a simple example should be sufficient for +most uses. Let's say we want to make our home directory and APT cache +persistent in an ext4 filesystem on the /dev/sdb1 partition: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Then we reboot. During the first boot the contents of #{/home}# and +#{/var/cache/apt}# will be copied into the persistence volume, and from then +on all changes to these directories will live in the persistence +volume. Please note that any paths listed in the #{persistence.conf}# file +cannot contain white spaces or the special #{.}# and #{..}# path +components. Also, neither #{/lib}#, #{/lib/live}# (or any of their +sub-directories) nor #{/}# can be made persistent using custom mounts. As a +workaround for this limitation you can add #{/ union}# to your +#{persistence.conf}# file to achieve full persistence. + +3~ Using more than one persistence store + +There are different methods of using multiple persistence store for +different use cases. For instance, using several volumes at the same time or +selecting only one, among various, for very specific purposes. + +Several different custom overlay volumes (with their own +#{persistence.conf}# files) can be used at the same time, but if several +volumes make the same directory persistent, only one of them will be +used. If any two mounts are "nested" (i.e. one is a sub-directory of the +other) the parent will be mounted before the child so no mount will be +hidden by the other. Nested custom mounts are problematic if they are listed +in the same #{persistence.conf}# file. See the persistence.conf(5) man page +for how to handle that case if you really need it (hint: you usually don't). + +One possible use case: If you wish to store the user data i.e. #{/home}# and +the superuser data i.e. #{/root}# in different partitions, create two +partitions with the #{persistence}# label and add a #{persistence.conf}# +file in each one like this, #{# echo "/home" > persistence.conf}# for the +first partition that will save the user's files and #{# echo "/root" > +persistence.conf}# for the second partition which will store the superuser's +files. Finally, use the #{persistence}# boot parameter. + +If a user would need multiple persistence store of the same type for +different locations or testing, such as #{private}# and #{work}#, the boot +parameter #{persistence-label}# used in conjunction with the boot parameter +#{persistence}# will allow for multiple but unique persistence media. An +example would be if a user wanted to use a persistence partition labeled +#{private}# for personal data like browser bookmarks or other types, they +would use the boot parameters: #{persistence}# +#{persistence-label=private}#. And to store work related data, like +documents, research projects or other types, they would use the boot +parameters: #{persistence}# #{persistence-label=work}#. + +It is important to remember that each of these volumes, #{private}# and +#{work}#, also needs a #{persistence.conf}# file in its root. The live-boot +man page contains more information about how to use these labels with legacy +names. + +3~ Using persistence with encryption + +Using the persistence feature means that some sensible data might get +exposed to risk. Especially if the persistent data is stored on a portable +device such as a usb stick or an external hard drive. That is when +encryption comes in handy. Even if the entire procedure might seem +complicated because of the number of steps to be taken, it is really easy to +handle encrypted partitions with live-boot. In order to use *{luks}*, which +is the supported encryption type, you need to install /{cryptsetup}/ both on +the machine you are creating the encrypted partition with and also in the +live system you are going to use the encrypted persistent partition with. + +To install /{cryptsetup}/ on your machine: + +code{ + + # apt-get install cryptsetup + +}code + +To install /{cryptsetup}/ in your live system, add it to your package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Once you have your live system with /{cryptsetup}/, you basically only need +to create a new partition, encrypt it and boot with the #{persistence}# and +#{persistence-encryption=luks}# parameters. We could have already +anticipated this step and added the boot parameters following the usual +procedure: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Let's go into the details for all of those who are not familiar with +encryption. In the following example we are going to use a partition on a +usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need +to determine which partition is the one you are going to use in your +specific case. + +The first step is plugging in your usb stick and determine which device it +is. The recommended method of listing devices in live-manual is using #{ls +-l /dev/disk/by-id}#. After that, create a new partition and then, encrypt +it with a passphrase as follows: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Then open the luks partition in the virtual device mapper. Use any name you +like. We use *{live}* here as an example: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +The next step is filling the device with zeros before creating the +filesystem: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Now, we are ready to create the filesystem. Notice that we are adding the +label #{persistence}# so that the device is mounted as persistence store at +boot time. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +To continue with our setup, we need to mount the device, for example in +#{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +And create the #{persistence.conf}# file in the root of the partition. This +is, as explained before, strictly necessary. See {The persistence.conf +file}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Then unmount the mount point: + +code{ + + # umount /mnt + +}code + +And optionally, although it might be a good way of securing the data we have +just added to the partition, we can close the device: + +code{ + + # cryptsetup luksClose live + +}code + +Let's summarize the process. So far, we have created an encryption capable +live system, which can be copied to a usb stick as explained in {Copying an +ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also +created an encrypted partition, which can be located in the same usb stick +to carry it around and we have configured the encrypted partition to be used +as persistence store. So now, we only need to boot the live system. At boot +time, live-boot will prompt us for the passphrase and will mount the +encrypted partition to be used for persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_installation.ssi new file mode 100644 index 0000000..7b15a48 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_installation.ssi @@ -0,0 +1,177 @@ +:B~ Instalação + +1~installation Instalação + +2~requirements Requisitos + +Building live system images has very few system requirements: + +_* Acesso superusuário (root) + +_* Uma versão atualizada do live-build + +_* Um shell compatível com POSIX, como /{bash}/ or /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6.x ou mais recente + +Observe que usar o Debian ou uma distribuição Debian derivada não é +necessária - live-build será executado em quase qualquer distribuição com os +requisitos acima. + +2~installing-live-build Instalando live-build + +Você pode instalar live-build em um número de caminhos diferentes: + +_* Do repositório Debian + +_* Da fonte + +_* Apartir de imagens + +Se você está usando o Debian, O caminho recomendado é instalar via +repositório Debian. + +3~ Do repositório Debian + +Basta instalar live-build como qualquer outro pacote: + +code{ + + # apt-get install live-build + +}code + +3~ Da fonte + +live-build foi desenvolvido usando o sistema de controle de versão Git. Em +sistemas baseados em Debian, esta é fornecida pelo pacote /{git}/. Para +verificar o código mais recente, execute: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +Você pode construir e instalar seu próprio pacote Debian executando: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Agora instale qualquer dos recém construídos arquivos #{.deb}# que você +estava interessado, por exemplo, + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +Você também pode instalar live-build diretamente ao seu sistema executando: + +code{ + + # make install + +}code + +e o desinstalar com: + +code{ + + # make uninstall + +}code + +3~ Dos 'instantaneos' + +Se você não deseja construir ou instalar live-build a partir da fonte, você +pode usar instantaneos. Estes são construídos automaticamente a partir da +versão mais recente no Git e estão disponíveis no +http://live-systems.org/debian/. + +2~ Instalando live-boot e live-config + +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. + +3~ Do repositório Debian + +Ambos live-boot e live-config estão disponíveis a partir do repositório +Debian como {Instalação do live-build}#installing-live-build. + +3~ Da fonte + +Para usar a última fonte de git, você pode seguir o processo +abaixo. Certifique-se de que você está familiarizado com os termos +mencionados em {Termos}#terms. + +_ * Consultar as fontes de live-boot e live-config + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consulte as páginas do man live-boot e live-config para obter detalhes sobre +a personalização, se essa é a sua razão para a construção desses pacotes a +partir da fonte. + +_* Construir os arquivos live-boot e live-config .deb + +You must build either on your target distribution or in a chroot containing +your target platform: this means if your target is ${testing} then you +should build against ${testing}. + +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to +build live-boot for a target distribution that differs from your build +system. For example, for ${testing} live images, build live-boot in a +${testing} chroot. If your target distribution happens to match your build +system distribution, you may build directly on the build system using +#{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Utilização de aplicativos .deb gerados + +As live-boot and live-config are installed by live-build system, installing +the packages in the host system is not sufficient: you should treat the +generated .deb files like any other custom packages. Since your purpose for +building from source is likely to test new things over the short term before +the official release, follow {Installing modified or third-party +packages}#installing-modified-or-third-party-packages to temporarily include +the relevant files in your configuration. In particular, notice that both +packages are divided into a generic part, a documentation part and one or +more back-ends. Include the generic part, only one back-end matching your +configuration, and optionally the documentation. Assuming you are building a +live image in the current directory and have generated all .deb files for a +single version of both packages in the directory above, these bash commands +would copy all of the relevant packages including default back-ends: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ Dos 'instantaneos' + +You can let live-build automatically use the latest snapshots of live-boot +and live-config by configuring the package repository on live-systems.org as +a third-party repository in your live-build configuration directory. diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_managing_a_configuration.ssi new file mode 100644 index 0000000..6d54371 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_managing_a_configuration.ssi @@ -0,0 +1,133 @@ +:B~ Managing a configuration + +1~managing-a-configuration Managing a configuration + +This chapter explains how to manage a live configuration from initial +creation, through successive revisions and successive releases of both the +live-build software and the live image itself. + +2~ Dealing with configuration changes + +Live configurations rarely are perfect on the first try. It may be fine to +pass #{lb config}# options from the command-line to perform a single build, +but it is more typical to revise those options and build again until you are +satisfied. To support these changes, you will need auto scripts which ensure +your configuration is kept in a consistent state. + +3~ Why use auto scripts? What do they do? + +The #{lb config}# command stores the options you pass to it in #{config/*}# +files along with many other options set to default values. If you run #{lb +config}# again, it will not reset any option that was defaulted based on +your initial options. So, for example, if you run #{lb config}# again with a +new value for #{--binary-images}#, any dependent options that were defaulted +for the old image type may no longer work with the new ones. Nor are these +files intended to be read or edited. They store values for over a hundred +options, so nobody, let alone yourself, will be able to see in these which +options you actually specified. And finally, if you run #{lb config}#, then +upgrade live-build and it happens to rename an option, #{config/*}# would +still contain variables named after the old option that are no longer valid. + +For all these reasons, #{auto/*}# scripts will make your life easier. They +are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# +commands that are designed to help you manage your configuration. The +#{auto/config}# script stores your #{lb config}# command with all desired +options, the #{auto/clean}# script removes the files containing +configuration variable values, and the #{auto/build}# script keeps a +#{build.log}# of each build. Each of these scripts is run automatically +every time you run the corresponding #{lb}# command. By using these scripts, +your configuration is easier to read and is kept internally consistent from +one revision to the next. Also, it will be much easier for you identify and +fix options which need to change when you upgrade live-build after reading +the updated documentation. + +3~ Use example auto scripts + +For your convenience, live-build comes with example auto shell scripts to +copy and edit. Start a new, default configuration, then copy the examples +into it: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Edit #{auto/config}#, adding any options as you see fit. For instance: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Now, each time you use #{lb config}#, #{auto/config}# will reset the +configuration based on these options. When you want to make changes to them, +edit the options in this file instead of passing them to #{lb config}#. When +you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files +along with any other build products. And finally, when you use #{lb build}#, +a log of the build will be written by #{auto/build}# in #{build.log}#. + +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. + +2~clone-configuration-via-git Clone a configuration published via Git + +Use the #{lb config --config}# option to clone a Git repository that +contains a live system configuration. If you would like to base your +configuration on one maintained by the ${project}, look at +http://live-systems.org/gitweb/ for the repository named #{live-images}# in +the category #{Packages}#. This repository contains the configurations for +the live systems {prebuilt images}#downloading-prebuilt-images. + +For example, to build a standard image, use the #{live-images}# repository +as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Edit #{auto/config}# and any other things you need in the #{config}# tree to +suit your needs. For example, the unofficial non-free prebuilt images are +made by simply adding #{--archive-areas "main contrib non-free"}#. + +You may optionally define a shortcut in your Git configuration by adding the +following to your #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +This enables you to use #{lso:}# anywhere you need to specify the address of +a #{live-systems.org}# git repository. If you also drop the optional +#{.git}# suffix, starting a new image using this configuration is as easy +as: + +code{ + + $ lb config --config lso:live-images + +}code + +Cloning the entire #{live-images}# repository pulls the configurations used +for several images. If you feel like building a different image after you +have finished with the first one, change to another directory and again and +optionally, make any changes to suit your needs. + +In any case, remember that every time you will have to build the image as +superuser: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_overview.ssi new file mode 100644 index 0000000..073a266 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/pt_BR/user_overview.ssi @@ -0,0 +1,130 @@ +:B~ Overview of tools + +1~overview-of-tools Overview of tools + +This chapter contains an overview of the three main tools used in building +live systems: live-build, live-boot and live-config. + +2~live-build The live-build package + +live-build is a collection of scripts to build live systems. These scripts +are also referred to as "commands". + +The idea behind live-build is to be a framework that uses a configuration +directory to completely automate and customize all aspects of building a +Live image. + +Many concepts are similar to those used to build Debian packages with +/{debhelper}/: + +_* The scripts have a central location for configuring their operation. In +/{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For +example, dh_install will look, among others, for a file called +#{debian/install}# to determine which files should exist in a particular +binary package. In much the same way, live-build stores its configuration +entirely under a #{config/}# subdirectory. + +_* The scripts are independent - that is to say, it is always safe to run +each command. + +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton +configuration directory. This could be considered to be similar to tools +such as /{dh-make}/. For more information about these tools, read on, since +the remainder of this section discuses the four most important +commands. Note that the preceding #{lb}# is a generic wrapper for live-build +commands. + +_* *{lb config}*: Responsible for initializing a Live system configuration +directory. See {The lb config command}#lb-config for more information. + +_* *{lb build}*: Responsible for starting a Live system build. See {The lb +build command}#lb-build for more information. + +_* *{lb clean}*: Responsible for removing parts of a Live system build. See +{The lb clean command}#lb-clean for more information. + +3~lb-config The #{lb config}# command + +As discussed in {live-build}#live-build, the scripts that make up live-build +read their configuration with the #{source}# command from a single directory +named #{config/}#. As constructing this directory by hand would be +time-consuming and error-prone, the #{lb config}# command can be used to +create the initial skeleton configuration tree. + +Issuing #{lb config}# without any arguments creates the #{config/}# +subdirectory which is populated with some default settings in configuration +files, and two skeleton trees named #{auto/}# and #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Using #{lb config}# without any arguments would be suitable for users who +need a very basic image, or who intend to provide a more complete +configuration via #{auto/config}# later (see {Managing a +configuration}#managing-a-configuration for details). + +Normally, you will want to specify some options. For example, to specify +which package manager to use while building the image: + +code{ + + $ lb config --apt aptitude + +}code + +It is possible to specify many options, such as: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +A full list of options is available in the #{lb_config}# man page. + +3~lb-build The #{lb build}# command + +The #{lb build}# command reads in your configuration from the #{config/}# +directory. It then runs the lower level commands needed to build your Live +system. + +3~lb-clean The #{lb clean}# command + +It is the job of the #{lb clean}# command to remove various parts of a build +so subsequent builds can start from a clean state. By default, #{chroot}#, +#{binary}# and #{source}# stages are cleaned, but the cache is left +intact. Also, individual stages can be cleaned. For example, if you have +made changes that only affect the binary stage, use #{lb clean --binary}# +prior to building a new binary. If your changes invalidate the bootstrap +and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or +#{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man +page for a full list of options. + +2~live-boot The live-boot package + +live-boot is a collection of scripts providing hooks for the +/{initramfs-tools}/, used to generate an initramfs capable of booting live +systems, such as those created by live-build. This includes the live system +ISOs, netboot tarballs, and USB stick images. + +At boot time it will look for read-only media containing a #{/live/}# +directory where a root filesystem (often a compressed filesystem image like +squashfs) is stored. If found, it will create a writable environment, using +aufs, for Debian like systems to boot from. + +More information on initial ramfs in Debian can be found in the Debian Linux +Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter +on initramfs. + +2~live-config The live-config package + +live-config consists of the scripts that run at boot time after live-boot to +configure the live system automatically. It handles such tasks as setting +the hostname, locales and timezone, creating the live user, inhibiting cron +jobs and performing autologin of the live user. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/about_manual.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/about_manual.ssi new file mode 100644 index 0000000..7270fcd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/about_manual.ssi @@ -0,0 +1,268 @@ +:B~ Despre acest manual + +1~about-manual Despre acest manual + +This manual serves as a single access point to all documentation related to +the ${project} and in particular applies to the software produced by the +project for the Debian 9.0 "${stable}" release. An up-to-date version can +always be found at http://live-systems.org/ + +While live-manual is primarily focused on helping you build a live system +and not on end-user topics, an end user may find some useful information in +these sections: {The Basics}#the-basics covers downloading prebuilt images +and preparing images to be booted from media or the network, either using +the web builder or running live-build directly on your system. {Customizing +run time behaviours}#customizing-run-time-behaviours describes some options +that may be specified at the boot prompt, such as selecting a keyboard +layout and locale, and using persistence. + +Anumite comenzi din text trebuie sa fie executate ca 'super_utilizator', +privilegiu care poate fi obtinut fie prin comanda #{su}#, sau +#{sudo}#. Pentru a distinge intre acesti utilizatori se vor folosi #{$}# +respectiv #{#}# . Aceste simboluri nu fac parte din comenzi. + +2~ For the impatient + +While we believe that everything in this manual is important to at least +some of our users, we realize it is a lot of material to cover and that you +may wish to experience early success using the software before delving into +the details. Therefore, we suggest reading in the following order. + +First, read this chapter, {About this manual}#about-manual, from the +beginning and ending with the {Terms}#terms section. Next, skip to the three +tutorials at the front of the {Examples}#examples section designed to teach +you image building and customization basics. Read {Using the +examples}#using-the-examples first, followed by {Tutorial 1: A default +image}#tutorial-1, {Tutorial 2: A web browser utility}#tutorial-2 and +finally {Tutorial 3: A personalized image}#tutorial-3. By the end of these +tutorials, you will have a taste of what can be done with live systems. + +We encourage you to return to more in-depth study of the manual, perhaps +next reading {The basics}#the-basics, skimming or skipping {Building a +netboot image}#building-netboot-image, and finishing by reading the +{Customization overview}#customization-overview and the chapters that follow +it. By this point, we hope you are thoroughly excited by what can be done +with live systems and motivated to read the rest of the manual, +cover-to-cover. + +2~terms Termeni + +_* *{Live system}*: An operating system that can boot without installation +to a hard drive. Live systems do not alter local operating system(s) or +file(s) already installed on the computer hard drive unless instructed to do +so. Live systems are typically booted from media such as CDs, DVDs or USB +sticks. Some may also boot over the network (via netboot images, see +{Building a netboot image}#building-netboot-image), and over the Internet +(via the boot parameter #{fetch=URL}#, see {Webbooting}#webbooting). + +_* *{Live medium}*: As distinct from live system, the live medium refers to +the CD, DVD or USB stick where the binary produced by live-build and used to +boot the live system is written. More broadly, the term also refers to any +place where this binary resides for the purposes of booting the live system, +such as the location for the network boot files. + +_* *{${project}}*: The project which maintains, among others, the live-boot, +live-build, live-config, live-tools and live-manual packages. + +_* *{Host system}*: Mediul folosit pentru crearea sistemului live pe un +sistem dat. + +_* *{Target system}*: Mediul folosit pentru rularea sistemului live. + +_* *{live-boot}*: O coloctie se scripte folosite la pornirea sistemului +live. + +_* *{live-build}*: A collection of scripts used to build customized live +systems. + +_* *{live-config}*: O colectie de scripte folosite la configurarea sitemului +live in timpul procesului de pornire. + +_* *{live-tools}*: A collection of additional scripts used to perform useful +tasks within a running live system. + +_* *{live-manual}*: Acest document face parte din pachetul numit +live-manual. + +_* *{Debian Installer (d-i)}*: Sistemul de instalare oficial pentru +distributia Debian. + +_* *{Boot parameters}*: Parameti care pot fi adaugati la promptul +bootloader-ului care sa infuenteze kernelul sau live-config. + +_* *{chroot}*: Programul /{chroot}/, #{chroot(8)}#, permite rularea a +diferite instante din mediul GNU/Linux pe un singur sistem si in simultan +fara a necesita o repornire a sistemului. + +_* *{Binary image}*: A file containing the live system, such as +live-image-i386.hybrid.iso or live-image-i386.img. + +_* *{Target distribution}*: Dea pe care se bazeaza sistemul live. Aceasta +distributie poate fi diferita de cea a sistemului gazda. + +_* *{stable/testing/unstable}*: The *{stable}* distribution, currently +codenamed ${stable}, contains the latest officially released distribution of +Debian. The *{testing}* distribution, temporarily codenamed ${testing}, is +the staging area for the next *{stable}* release. A major advantage of using +this distribution is that it has more recent versions of software relative +to the *{stable}* release. The *{unstable}* distribution, permanently +codenamed sid, is where active development of Debian occurs. Generally, this +distribution is run by developers and those who like to live on the +edge. Throughout the manual, we tend to use codenames for the releases, such +as ${testing} or sid, as that is what is supported by the tools themselves. + +2~ Autori + +Lista autorilor (in ordine alfabetica): + +_* Ben Armstrong + +_* Brendan Sleight + +_* Carlos Zuferri + +_* Chris Lamb + +_* Daniel Baumann + +_* Franklin Piat + +_* Jonas Stein + +_* Kai Hendry + +_* Marco Amadori + +_* Mathieu Geli + +_* Matthias Kirschner + +_* Richard Nelson + +_* Trent W. Buck + +2~how-to-contribute Cum se poate contribui la acest document + +This manual is intended as a community project and all proposals for +improvements and contributions are extremely welcome. Please see the section +{Contributing to the project}#contributing-to-project for detailed +information on how to fetch the commit key and make good commits. + +3~applying-changes Applying changes + +In order to make changes to the English manual you have to edit the right +files in #{manual/en/}# but prior to the submission of your contribution, +please preview your work. To preview the live-manual, ensure the packages +needed for building it are installed by executing: + +code{ + + # apt-get install make po4a ruby ruby-nokogiri sisu-complete + +}code + +Pute-ti crea live-manual de la nivelul de sus al directorului Git checkout +al dvs, prin executatea: + +code{ + + $ make build + +}code + +Since it takes a while to build the manual in all supported languages, +authors may find it convenient to use one of the fast proofing shortcuts +when reviewing the new documentation they have added to the English +manual. Using #{PROOF=1}# builds live-manual in html format, but without the +segmented html files, and using #{PROOF=2}# builds live-manual in pdf +format, but only the A4 and letter portraits. That is why using either of +the #{PROOF=}# possibilities can save up a considerable amount of time, e.g: + +code{ + + $ make build PROOF=1 + +}code + +When proofing one of the translations it is possible to build only one +language by executing, e.g: + +code{ + + $ make build LANGUAGES=de + +}code + +It is also possible to build by document type, e.g: + +code{ + + $ make build FORMATS=pdf + +}code + +Or combine both, e.g: + +code{ + + $ make build LANGUAGES=de FORMATS=html + +}code + +After revising your work and making sure that everything is fine, do not use +#{make commit}# unless you are updating translations in the commit, and in +that case, do not mix changes to the English manual and translations in the +same commit, but use separate commits for each. See the +{Translation}#translation section for more details. + +3~translation Translation + +In order to translate live-manual, follow these steps depending on whether +you are starting a translation from scratch or continue working on an +already existing one: + +_* Start a new translation from scratch + +_2* Translate the *{about_manual.ssi.pot}*, *{about_project.ssi.pot}* and +*{index.html.in.pot}* files in #{manual/pot/}# to your language with your +favourite editor (such as /{poedit}/) and send the translated #{.po}# files +to the mailing list to check their integrity. live-manual's integrity check +not only ensures that the #{.po}# files are 100% translated but it also +detects possible errors. + +_2* Once checked, to enable a new language in the autobuild it is enough to +add the initial translated files to #{manual/po/${LANGUAGE}/}# and run +#{make commit}#. And then, edit #{manual/_sisu/home/index.html}# adding the +name of the language and its name in English between brackets. + +_* Continue with an already started translation + +_2* If your target language has already been added, you can randomly +continue translating the remaining .po files in #{manual/po/${LANGUAGE}/}# +using your favourite editor (such as /{poedit}/). + +_2* Do not forget that you need to run #{make commit}# to ensure that the +translated manuals are updated from the .po files and then you can review +your changes launching #{make build}# before #{git add .}#, #{git commit -m +"Translating..."}# and #{git push}#. Remember that since #{make build}# can +take a considerable amount of time, you can proofread languages individually +as explained in {Applying changes}#applying-changes + +After running #{make commit}# you will see some text scroll by. These are +basically informative messages about the processing status and also some +hints about what can be done in order to improve live-manual. Unless you see +a fatal error, you usually can proceed and submit your contribution. + +live-manual comes with two utilities that can greatly help translators to +find untranslated and changed strings. The first one is "make translate". It +launches an script that tells you in detail how many untranslated strings +there are in each .po file. The second one, the "make fixfuzzy" target, only +acts upon changed strings but it helps you to find and fix them one by one. + +Keep in mind that even though these utilities might be really helpful to do +translation work on the command line, the use of an specialized tool like +/{poedit}/ is the recommended way to do the task. It is also a good idea to +read the Debian localization (l10n) documentation and, specifically to +live-manual, the {Guidelines for translators}#guidelines-translators. + +*{Note:}* You can use #{make clean}# to clean your git tree before pushing. This step is not compulsory thanks to the .gitignore file but it is a good practice to avoid committing files involuntarily. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/about_project.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/about_project.ssi new file mode 100644 index 0000000..433bb34 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/about_project.ssi @@ -0,0 +1,104 @@ +:B~ About the ${project} + +1~about-project About the ${project} + +2~ Motivatie + +3~ Ce nu e bine cu sistemele live actuale + +When ${project} was initiated, there were already several Debian based live +systems available and they are doing a great job. From the Debian +perspective most of them have one or more of the following disadvantages: + +_* Ele nu sunt proiecte Debian si drept urmare nu au suport din partea +Comunitatii Debian + +_* Ele amalgameaza diferite distributii, ca *{testing}* si *{unstable}*. + +_* Ele suporta doar arhitectura i386. + +_* Ele au modificat comportamentul si /sau aspectul programelor pentru a +castuga spatiu. + +_* Acestea includ pachete din afara arhivelor Debian + +_* Ele folosesc kernele modificate care contin patch-uri ce nu fac parte din +Debian. + +_* Ele sunt greoaie si lente datorete marimii lor si deci inapropiate pentru +situatii de salvare/rescue. + +_* Ele nu sunt disponibile in diferite sosuri ca CDs, DVDs, USB-stick si +netboot images. + +3~ De ce e nevoie de propriul nostru sistem live ? + +Debian se considera Sistemul de Operare Universal: Are un mecanism live +pentru a se promova in jur si de a prezenta cu acuratete sistemul de operare +ce are urmatoarele mari avantaje: + +_* It is a subproject of Debian. + +_* El reflecta starea (actuala) a distributiei. + +_* Se poate utiliza pe maximum de arhitecturi posibile. + +_* Contine doar programe Debian. + +_* Nu contine nici un pachet care nu este din afara arhivelor Debian. + +_* Foloseste un kernel Debian nealterat, fara patch-uri aditionale. + +2~ Filozofia + +3~ Numai pachete neschimbate din Debian "main" + +Se vor folosi numai pachete din depozitul Debian sectiunea "main". Sectiunea +non-free nu este parte a Debian drept urmare nu poate fi folosita nici un +fel la construirea imaginilor live cu Debian. + +Nu vor fi facute nici o schimbare in programe. Daca este nevoie de acest +lucru, schimbarile vor fi facute in coordonare cu responsabilul de program +din Debian. + +Ca o exceptie, programele specifice ca live-boot, live-build sau live-config +pot fi folosite temporar din depozitele proprii live, pentru nevoi de +dezvoltare. (de exemplu pentru creerea de development snapshots). Acestea +vor fi upload-ate in Debian la date cuvenite. + +3~ Nu vor fi programe de configurare pentru sistemul live. + +In aceasta faza nu vor fi propuse sau instalate example sau configuratii +alternative. Toate programele sunt folosite cu configuratia default 'de +baza', la fel ca in instalatia normaladin Debian. + +In caz de nevoie a unei configuratii diferite, aceasta schimbare va fii +facuta in coordonare cu responsabilui de program din Debian. + +A system for configuring packages is provided using debconf allowing custom +configured packages to be installed in your custom produced live system +images, but for the {prebuilt live images}#downloading-prebuilt-images we +choose to leave packages in their default configuration, unless absolutely +necessary in order to work in the live environment. Wherever possible, we +prefer to adapt packages within the Debian archive to work better in a live +system versus making changes to the live toolchain or {prebuilt image +configurations}#clone-configuration-via-git. For more information, please +see {Customization overview}#customization-overview. + +2~contact Contact + +_* *{Mailing list}*: The primary contact for the project is the mailing list +at https://lists.debian.org/debian-live/. You can email the list directly by +addressing your mail to debian-live@lists.debian.org. The list archives are +available at https://lists.debian.org/debian-live/. + +_* *{IRC}*: Un numar de utilizatori si dezvoltatori sunt prezenti in canalul +#debian-live pe n irc.debian.org (OFTC). Daca aveti o intrebare pentru IRC , +fiti cu multa rabdare in asteptarea raspunsului. In caz de lipsa a unui +raspuns , folositi mailing list. + +_* *{BTS}*: BTS adica {Debian Bug Tracking +System}https://www.debian.org/Bugs/ contine detalii asupra rapoartelor de +bug facute de utilizatorisau dezvoltatori. Fiecare bug are un numar, si este +mentinut deschis pana la rezolvare. Alte informatii gasiti la {Reporting +bugs}#bugs. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/appendix_style-guide.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/appendix_style-guide.ssi new file mode 100644 index 0000000..1bba13e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/appendix_style-guide.ssi @@ -0,0 +1,364 @@ +:B~ Style guide + +1~style-guide Style guide + +2~ Guidelines for authors + +This section deals with some general considerations to be taken into account +when writing technical documentation for live-manual. They are divided into +linguistic features and recommended procedures. + +*{Note:}* Authors should first read {Contributing to this document}#how-to-contribute + +3~ Linguistic features + +_* /{Use plain English}/ + +Keep in mind that a high percentage of your readers are not native speakers +of English. So as a general rule try to use short, meaningful sentences, +followed by a full stop. + +This does not mean that you have to use a simplistic, naive style. It is a +suggestion to try to avoid, as much as possible, complex subordinate +sentences that make the text difficult to understand for non-native speakers +of English. + +_* /{Variety of English}/ + +The most widely spread varieties of English are British and American so it +is very likely that most authors will use either one or the other. In a +collaborative environment, the ideal variety would be "International +English" but it is very difficult, not to say impossible, to decide on which +variety among all the existing ones, is the best to use. + +We expect that different varieties may mix without creating +misunderstandings but in general terms you should try to be coherent and +before deciding on using British, American or any other English flavour at +your discretion, please take a look at how other people write and try to +imitate them. + +_* /{Be balanced}/ + +Do not be biased. Avoid including references to ideologies completely +unrelated to live-manual. Technical writing should be as neutral as +possible. It is in the very nature of scientific writing. + +_* /{Be politically correct}/ + +Try to avoid sexist language as much as possible. If you need to make +references to the third person singular preferably use "they" rather than +"he" or "she" or awkward inventions such as "s/he", "s(he)" and the like. + +_* /{Be concise}/ + +Go straight to the point and do not wander around aimlessly. Give as much +information as necessary but do not give more information than necessary, +this is to say, do not explain unnecessary details. Your readers are +intelligent. Presume some previous knowledge on their part. + +_* /{Minimize translation work}/ + +Keep in mind that whatever you write will have to be translated into several +other languages. This implies that a number of people will have to do an +extra work if you add useless or redundant information. + +_* /{Be coherent}/ + +As suggested before, it is almost impossible to standardize a collaborative +document into a perfectly unified whole. However, every effort on your side +to write in a coherent way with the rest of the authors will be appreciated. + +_* /{Be cohesive}/ + +Use as many text-forming devices as necessary to make your text cohesive and +unambiguous. (Text-forming devices are linguistic markers such as +connectors). + +_* /{Be descriptive}/ + +It is preferable to describe the point in one or several paragraphs than +merely using a number of sentences in a typical "changelog" style. Describe +it! Your readers will appreciate it. + +_* /{Dictionary}/ + +Look up the meaning of words in a dictionary or encyclopedia if you do not +know how to express certain concepts in English. But keep in mind that a +dictionary can either be your best friend or can turn into your worst enemy +if you do not know how to use it correctly. + +English has the largest vocabulary that exists (with over one million +words). Many of these words are borrowings from other languages. When +looking up the meaning of words in a bilingual dictionary the tendency of a +non-native speaker of English is to choose the one that sounds more similar +in their mother tongue. This often turns into an excessively formal +discourse which does not sound quite natural in English. + +As a general rule, if a concept can be expressed using different synonyms, +it is a good advice to choose the first word proposed by the dictionary. If +in doubt, choosing words of Germanic origin (Usually monosyllabic words) is +often the right thing to do. Be warned that these two techniques might +produce a rather informal discourse but at least your choice of words will +be of wide use and generally accepted. + +Using a dictionary of collocations is recommended. They are extremely +helpful when it comes to know which words usually occur together. + +Again it is a good practice to learn from the work of others. Using a search +engine to check how other authors use certain expressions may help a lot. + +_* /{False friends, idioms and other idiomatic expressions}/ + +Watch out for false friends. No matter how proficient you are in a foreign +language you cannot help falling from time to time in the trap of the so +called "false friends", words that look similar in two languages but whose +meanings or uses might be completely different. + +Try to avoid idioms as much as possible. "Idioms" are expressions that may +convey a completely different meaning from what their individual words seem +to mean. Sometimes, idioms might be difficult to understand even for native +speakers of English! + +_* /{Avoid slang, abbreviations, contractions...}/ + +Even though you are encouraged to use plain, everyday English, technical +writing belongs to the formal register of the language. + +Try to avoid slang, unusual abbreviations that are difficult to understand +and above all contractions that try to imitate the spoken language. Not to +mention typical irc and family friendly expressions. + +3~ Procedures + +_* /{Test before write}/ + +It is important that authors test their examples before adding them to +live-manual to ensure that everything works as described. Testing on a clean +chroot or VM can be a good starting point. Besides, it would be ideal if the +tests were then carried out on different machines with different hardware to +spot possible problems that may arise. + +_* /{Examples}/ + +When providing an example try to be as specific as you can. An example is, +after all, just an example. + +It is often better to use a line that only applies to a specific case than +using abstractions that may confuse your readers. In this case you can +provide a brief explanation of the effects of the proposed example. + +There may be some exceptions when the example suggests using some +potentially dangerous commands that, if misused, may cause data loss or +other similar undesirable effects. In this case you should provide a +thorough explanation of the possible side effects. + +_* /{External links}/ + +Links to external sites should only be used when the information on those +sites is crucial when it comes to understanding a special point. Even so, +try to use links to external sites as sparsely as possible. Internet links +are likely to change from time to time resulting in broken links and leaving +your arguments in an incomplete state. + +Besides, people who read the manual offline will not have the chance to +follow those links. + +_* /{Avoid branding and things that violate the license under which the +manual is published}/ + +Try to avoid branding as much as possible. Keep in mind that other +downstream projects might make use of the documentation you write. So you +are complicating things for them if you add certain specific material. + +live-manual is licensed under the GNU GPL. This has a number of implications +that apply to the distribution of the material (of any kind, including +copyrighted graphics or logos) that is published with it. + +_* /{Write a first draft, revise, edit, improve, redo if necessary}/ + + - Brainstorm!. You need to organize your ideas first in a logical sequence + of events. + + - Once you have somehow organized those ideas in your mind write a first + draft. + + - Revise grammar, syntax and spelling. Keep in mind that the proper names + of the releases, such as ${testing} or sid, should not be capitalized + when referred to as code names. In order to check the spelling you can + run the "spell" target. i.e. #{make spell}# + + - Improve your statements and redo any part if necessary. + +_* /{Chapters}/ + +Use the conventional numbering system for chapters and subtitles. e.g. 1, +1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 ... and so on. See markup +below. + +If you have to enumerate a series of steps or stages in your description, +you can also use ordinal numbers: First, second, third ... or First, Then, +After that, Finally ... Alternatively you can use bulleted items. + +_* /{Markup}/ + +And last but not least, live-manual uses {SiSU}http://www.sisudoc.org/ to +process the text files and produce a multiple format output. It is +recommended to take a look at {SiSU's +manual}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html to get +familiar with its markup, or else type: + +code{ + + $ sisu --help markup + +}code + +Here are some markup examples that may prove useful: + + - For emphasis/bold text: + +code{ + +*{foo}* or !{foo}! + +}code + +produces: *{foo}* or !{foo}!. Use it to emphasize certain key words. + + - For italics: + +code{ + +/{foo}/ + +}code + +produces: /{foo}/. Use them e.g. for the names of Debian packages. + + - For monospace: + +code{ + +#{foo}# + +}code + +produces: #{foo}#. Use it e.g. for the names of commands. And also to +highlight some key words or things like paths. + + - For code blocks: + +code{ + + code{ + + $ foo + # bar + + }code + +}code + +produces: + +code{ + + $ foo + # bar + +}code + +Use #{code{}# to open and #{}code}# to close the tags. It is important to +remember to leave a space at the beginning of each line of code. + +2~guidelines-translators Guidelines for translators + +This section deals with some general considerations to be taken into account +when translating the contents of live-manual. + +As a general recommendation, translators should have read and understood the +translation rules that apply to their specific languages. Usually, +translation groups and mailing lists provide information on how to produce +translated work that complies with Debian quality standards. + +*{Note:}* Translators should also read {Contributing to this document}#how-to-contribute. In particular the section {Translation}#translation + +3~ Translation hints + +_* /{Comments}/ + +The role of the translator is to convey as faithfully as possible the +meaning of words, sentences, paragraphs and texts as written by the original +authors into their target language. + +So they should refrain from adding personal comments or extra bits of +information of their own. If they want to add a comment for other +translators working on the same documents, they can leave it in the space +reserved for that. That is, the header of the strings in the *{po}* files +preceded by a number sign *{#}*. Most graphical translation programs can +automatically handle those types of comments. + +_* /{TN, Translator's Note}/ + +It is perfectly acceptable however, to include a word or an expression in +brackets in the translated text if, and only if, that makes the meaning of a +difficult word or expression clearer to the reader. Inside the brackets the +translator should make evident that the addition was theirs using the +abbreviation "TN" or "Translator's Note". + +_* /{Impersonal sentences}/ + +Documents written in English make an extensive use of the impersonal form +"you". In some other languages that do not share this characteristic, this +might give the false impression that the original texts are directly +addressing the reader when they are actually not doing so. Translators must +be aware of that fact and reflect it in their language as accurately as +possible. + +_* /{False friends}/ + +The trap of "false friends" explained before especially applies to +translators. Double check the meaning of suspicious false friends if in +doubt. + +_* /{Markup}/ + +Translators working initially with *{pot}* files and later on with *{po}* +files will find many markup features in the strings. They can translate the +text anyway, as long as it is translatable, but it is extremely important +that they use exactly the same markup as the original English version. + +_* /{Code blocks}/ + +Even though the code blocks are usually untranslatable, including them in +the translation is the only way to score a 100% complete translation. And +even though it means more work at first because it might require the +intervention of the translators if the code changes, it is the best way, in +the long run, to identify what has already been translated and what has not +when checking the integrity of the .po files. + +_* /{Newlines}/ + +The translated texts need to have the exact same newlines as the original +texts. Be careful to press the "Enter" key or type *{\n}* if they appear in +the original files. These newlines often appear, for instance, in the code +blocks. + +Make no mistake, this does not mean that the translated text needs to have +the same length as the English version. That is nearly impossible. + +_* /{Untranslatable strings}/ + +Translators should never translate: + + - The code names of releases (which should be written in lowercase) + + - The names of programs + + - The commands given as examples + + - Metadata (often between colons *{:metadata:}*) + + - Links + + - Paths diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/examples.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/examples.ssi new file mode 100644 index 0000000..b793398 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/examples.ssi @@ -0,0 +1,434 @@ +:B~ Exemple + +1~examples Examples + +This chapter covers example builds for specific use cases with live +systems. If you are new to building your own live system images, we +recommend you first look at the three tutorials in sequence, as each one +teaches new techniques that will help you use and understand the remaining +examples. + +2~using-the-examples Using the examples + +To use these examples you need a system to build them on that meets the +requirements listed in {Requirements}#requirements and has live-build +installed as described in {Installing live-build}#installing-live-build. + +Note that, for the sake of brevity, in these examples we do not specify a +local mirror to use for the build. You can speed up downloads considerably +if you use a local mirror. You may specify the options when you use #{lb +config}#, as described in {Distribution mirrors used at build +time}#distribution-mirrors-build-time, or for more convenience, set the +default for your build system in #{/etc/live/build.conf}#. Simply create +this file and in it, set the corresponding #{LB_MIRROR_*}# variables to your +preferred mirror. All other mirrors used in the build will be defaulted from +these values. For example: + +code{ + + LB_MIRROR_BOOTSTRAP="http://mirror/debian/" + LB_MIRROR_CHROOT_SECURITY="http://mirror/debian-security/" + LB_MIRROR_CHROOT_BACKPORTS="http://mirror/debian-backports/" + +}code + +2~tutorial-1 Tutorial 1: A default image + +*{Use case:}* Create a simple first image, learning the basics of live-build. + +In this tutorial, we will build a default ISO hybrid live system image +containing only base packages (no Xorg) and some live system support +packages, as a first exercise in using live-build. + +You can't get much simpler than this: + +code{ + + $ mkdir tutorial1 ; cd tutorial1 ; lb config + +}code + +Examine the contents of the #{config/}# directory if you wish. You will see +stored here a skeletal configuration, ready to customize or, in this case, +use immediately to build a default image. + +Now, as superuser, build the image, saving a log as you build with #{tee}#. + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Assuming all goes well, after a while, the current directory will contain +#{live-image-i386.hybrid.iso}#. This ISO hybrid image can be booted directly +in a virtual machine as described in {Testing an ISO image with +Qemu}#testing-iso-with-qemu and {Testing an ISO image with +VirtualBox}#testing-iso-with-virtualbox, or else imaged onto optical media +or a USB flash device as described in {Burning an ISO image to a physical +medium}#burning-iso-image and {Copying an ISO hybrid image to a USB +stick}#copying-iso-hybrid-to-usb, respectively. + +2~tutorial-2 Tutorial 2: A web browser utility + +*{Use case:}* Create a web browser utility image, learning how to apply customizations. + +In this tutorial, we will create an image suitable for use as a web browser +utility, serving as an introduction to customizing live system images. + +code{ + + $ mkdir tutorial2 + $ cd tutorial2 + $ lb config + $ echo "task-lxde-desktop iceweasel" >> config/package-lists/my.list.chroot + +}code + +Our choice of LXDE for this example reflects our desire to provide a minimal +desktop environment, since the focus of the image is the single use we have +in mind, the web browser. We could go even further and provide a default +configuration for the web browser in +#{config/includes.chroot/etc/iceweasel/profile/}#, or additional support +packages for viewing various kinds of web content, but we leave this as an +exercise for the reader. + +Build the image, again as superuser, keeping a log as in {Tutorial +1}#tutorial-1: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +Again, verify the image is OK and test, as in {Tutorial 1}#tutorial-1. + +2~tutorial-3 Tutorial 3: A personalized image + +*{Use case:}* Create a project to build a personalized image, containing your favourite software to take with you on a USB stick wherever you go, and evolving in successive revisions as your needs and preferences change. + +Since we will be changing our personalized image over a number of revisions, +and we want to track those changes, trying things experimentally and +possibly reverting them if things don't work out, we will keep our +configuration in the popular #{git}# version control system. We will also +use the best practice of autoconfiguration via #{auto}# scripts as described +in {Managing a configuration}#managing-a-configuration. + +3~ First revision + +code{ + + $ mkdir -p tutorial3/auto + $ cp /usr/share/doc/live-build/examples/auto/* tutorial3/auto/ + $ cd tutorial3 + +}code + +Edit #{auto/config}# to read as follows: + +code{ + + #!/bin/sh + + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + "${@}" + +}code + +Perform #{lb config}# to generate the config tree, using the #{auto/config}# +script you just created: + +code{ + + $ lb config + +}code + +Now populate your local package list: + +code{ + + $ echo "task-lxde-desktop iceweasel xchat" >> config/package-lists/my.list.chroot + +}code + +First, #{--architectures i386}# ensures that on our #{amd64}# build system, +we build a 32-bit version suitable for use on most machines. Second, we use +#{--linux-flavours 686-pae}# because we don't anticipate using this image on +much older systems. Third, we have chosen the /{lxde}/ task metapackage to +give us a minimal desktop. And finally, we have added two initial favourite +packages: /{iceweasel}/ and /{xchat}/. + +Now, build the image: + +code{ + + # lb build + +}code + +Note that unlike in the first two tutorials, we no longer have to type +#{2>&1 | tee build.log}# as that is now included in #{auto/build}#. + +Once you've tested the image (as in {Tutorial 1}#tutorial-1) and are +satisfied it works, it's time to initialize our #{git}# repository, adding +only the auto scripts we just created, and then make the first commit: + +code{ + + $ git init + $ cp /usr/share/doc/live-build/examples/gitignore .gitignore + $ git add . + $ git commit -m "Initial import." + +}code + +3~ Second revision + +In this revision, we're going to clean up from the first build, add the +/{vlc}/ package to our configuration, rebuild, test and commit. + +The #{lb clean}# command will clean up all generated files from the previous +build except for the cache, which saves having to re-download packages. This +ensures that the subsequent #{lb build}# will re-run all stages to +regenerate the files from our new configuration. + +code{ + + # lb clean + +}code + +Now append the /{vlc}/ package to our local package list in +#{config/package-lists/my.list.chroot}#: + +code{ + + $ echo vlc >> config/package-lists/my.list.chroot + +}code + +Build again: + +code{ + +# lb build + +}code + +Test, and when you're satisfied, commit the next revision: + +code{ + + $ git commit -a -m "Adding vlc media player." + +}code + +Of course, more complicated changes to the configuration are possible, +perhaps adding files in subdirectories of #{config/}#. When you commit new +revisions, just take care not to hand edit or commit the top-level files in +#{config}# containing #{LB_*}# variables, as these are build products, too, +and are always cleaned up by #{lb clean}# and re-created with #{lb config}# +via their respective #{auto}# scripts. + +We've come to the end of our tutorial series. While many more kinds of +customization are possible, even just using the few features explored in +these simple examples, an almost infinite variety of different images can be +created. The remaining examples in this section cover several other use +cases drawn from the collected experiences of users of live systems. + +2~ A VNC Kiosk Client + +*{Use case:}* Create an image with live-build to boot directly to a VNC server. + +Make a build directory and create an skeletal configuration inside it, +disabling recommends to make a minimal system. And then create two initial +package lists: the first one generated with a script provided by live-build +named #{Packages}# (see {Generated package lists}#generated-package-lists), +and the second one including /{xorg}/, /{gdm3}/, /{metacity}/ and +/{xvnc4viewer}/. + +code{ + + $ mkdir vnc-kiosk-client + $ cd vnc-kiosk-client + $ lb config -a i386 -k 686-pae --apt-recommends false + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo "xorg gdm3 metacity xvnc4viewer" > config/package-lists/my.list.chroot + +}code + +As explained in {Tweaking APT to save space}#tweaking-apt-to-save-space you +may need to re-add some recommended packages to make your image work +properly. + +An easy way to list recommends is using /{apt-cache}/. For example: + +code{ + + $ apt-cache depends live-config live-boot + +}code + +In this example we found out that we had to re-include several packages +recommended by live-config and live-boot: #{user-setup}# to make autologin +work and #{sudo}# as an essential program to shutdown the system. Besides, +it could be handy to add #{live-tools}# to be able to copy the image to RAM +and #{eject}# to eventually eject the live medium. So: + +code{ + + $ echo "live-tools user-setup sudo eject" > config/package-lists/recommends.list.chroot + +}code + +After that, create the directory #{/etc/skel}# in #{config/includes.chroot}# +and put a custom #{.xsession}# in it for the default user that will launch +/{metacity}/ and start /{xvncviewer}/, connecting to port #{5901}# on a +server at #{192.168.1.2}#: + +code{ + + $ mkdir -p config/includes.chroot/etc/skel + $ cat > config/includes.chroot/etc/skel/.xsession << EOF + #!/bin/sh + + /usr/bin/metacity & + /usr/bin/xvncviewer 192.168.1.2:1 + + exit + EOF + +}code + +Build the image: + +code{ + + # lb build + +}code + +Enjoy. + +2~ A base image for a 128MB USB key + +*{Use case:}* Create a default image with some components removed in order to fit on a 128MB USB key with a little space left over to use as you see fit. + +When optimizing an image to fit a certain media size, you need to understand +the tradeoffs you are making between size and functionality. In this +example, we trim only so much as to make room for additional material within +a 128MB media size, but without doing anything to destroy the integrity of +the packages contained within, such as the purging of locale data via the +/{localepurge}/ package, or other such "intrusive" optimizations. Of +particular note, we use #{--debootstrap-options}# to create a minimal system +from scratch. + +code{ + + $ lb config --apt-indices false --apt-recommends false --debootstrap-options "--variant=minbase" --firmware-chroot false --memtest none + +}code + +To make the image work properly, we must re-add, at least, two recommended +packages which are left out by the #{--apt-recommends false}# option. See +{Tweaking APT to save space}#tweaking-apt-to-save-space + +code{ + + $ echo "user-setup sudo" > config/package-lists/recommends.list.chroot + +}code + +Now, build the image in the usual way: + +code{ + + # lb build 2>&1 | tee build.log + +}code + +On the author's system at the time of writing this, the above configuration +produced a 110MB image. This compares favourably with the 192MB image +produced by the default configuration in {Tutorial 1}#tutorial-1. + +Leaving off APT's indices with #{--apt-indices false}# saves a fair amount +of space, the tradeoff being that you need to do an #{apt-get update}# +before using /{apt}/ in the live system. Dropping recommended packages with +#{--apt-recommends false}# saves some additional space, at the expense of +omitting some packages you might otherwise expect to be +there. #{--debootstrap-options "--variant=minbase"}# bootstraps a minimal +system from the start. Not automatically including firmware packages with +#{--firmware-chroot false}# saves some space too. And finally, #{--memtest +none}# prevents the installation of a memory tester. + +*{Note:}* A minimal system can also be achieved using hooks, like for example the #{stripped.hook.chroot}# hook found in #{/usr/share/doc/live-build/examples/hooks}#. It may shave off additional small amounts of space and produce an image of 91MB. However, it does so by removal of documentation and other files from packages installed on the system. This violates the integrity of those packages and that, as the comment header warns, may have unforeseen consequences. That is why using a minimal /{debootstrap}/ is the recommended way of achieving this goal. + +2~ A localized GNOME desktop and installer + +*{Use case:}* Create a GNOME desktop image, localized for Switzerland and including an installer. + +We want to make an iso-hybrid image for i386 architecture using our +preferred desktop, in this case GNOME, containing all of the same packages +that would be installed by the standard Debian installer for GNOME. + +Our initial problem is the discovery of the names of the appropriate +language tasks. Currently, live-build cannot help with this. While we might +get lucky and find this by trial-and-error, there is a tool, #{grep-dctrl}#, +which can be used to dig it out of the task descriptions in tasksel-data, so +to prepare, make sure you have both of those things: + +code{ + + # apt-get install dctrl-tools tasksel-data + +}code + +Now we can search for the appropriate tasks, first with: + +code{ + + $ grep-dctrl -FTest-lang de /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german + +}code + +By this command, we discover the task is called, plainly enough, german. Now +to find the related tasks: + +code{ + + $ grep-dctrl -FEnhances german /usr/share/tasksel/descs/debian-tasks.desc -sTask + Task: german-desktop + Task: german-kde-desktop + +}code + +At boot time we will generate the *{de_CH.UTF-8}* locale and select the +*{ch}* keyboard layout. Now let's put the pieces together. Recalling from +{Using metapackages}#using-metapackages that task metapackages are prefixed +#{task-}#, we just specify these language boot parameters, then add standard +priority packages and all our discovered task metapackages to our package +list as follows: + +code{ + + $ mkdir live-gnome-ch + $ cd live-gnome-ch + $ lb config \ + -a i386 \ + --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" \ + --debian-installer live + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + $ echo task-gnome-desktop task-german task-german-desktop >> config/package-lists/desktop.list.chroot + $ echo debian-installer-launcher >> config/package-lists/installer.list.chroot + +}code + +Note that we have included the /{debian-installer-launcher}/ package to +launch the installer from the live desktop. The #{586}# kernel flavour, +which is currently necessary for the launcher to work properly, will be +included by default. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/live-manual.ssm b/markup/pod-samples/pod/live-manual/media/text/ro/live-manual.ssm new file mode 100644 index 0000000..22bc43e --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/live-manual.ssm @@ -0,0 +1,75 @@ +# SiSU 2.0 + +title: "Manualul Live Systems" + +creator: + author: "Proiectul Live Systems <debian-live@lists.debian.org>" + +rights: + copyright: "Copyright (C) 2006-2015 Live Systems Project" + license: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \\ \\ This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \\ \\ You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. \\ \\ The complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file." + +date: + published: "2015-08-23" + +publisher: "Proiectul Live Systems <debian-live@lists.debian.org>" + +classify: + topic_register: "SiSU markup sample:technical writing;software:program" + +make: + num_top: "1" + bold: "\\$\\{stable\\}|\\$\\{testing\\}|stretch|buster|sid" + italics: "live-boot|live-build|live-config|live-config-sysvinit|live-config-systemd|live-manual|live-tools|live-images|live-installer|debian-installer-launcher" +# bold: "[$][{]stable[}]|[$][{]testing[}]|stretch|buster|sid" +# substitute: "/${stable}/,'stretch' /${testing}/,'buster' /${project}/,'Live Systems Project'" + +:A~ @title + +:B~ Despre + +<< about_manual.ssi + +<< about_project.ssi + +:B~ Utilizator + +<< user_installation.ssi + +<< user_basics.ssi + +<< user_overview.ssi + +<< user_managing_a_configuration.ssi + +<< user_customization-overview.ssi + +<< user_customization-packages.ssi + +<< user_customization-contents.ssi + +<< user_customization-runtime.ssi + +<< user_customization-binary.ssi + +<< user_customization-installer.ssi + +:B~ Proiect + +<< project_contributing.ssi + +<< project_bugs.ssi + +<< project_coding-style.ssi + +<< project_procedures.ssi + +<< project_git.ssi + +:B~ Exemple + +<< examples.ssi + +:B~ Anexă + +<< appendix_style-guide.ssi diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/project_bugs.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/project_bugs.ssi new file mode 100644 index 0000000..76a0eba --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/project_bugs.ssi @@ -0,0 +1,206 @@ +:B~ Reporting bugs + +1~bugs Reporting bugs + +Live systems are far from being perfect, but we want to make it as close as +possible to perfect - with your help. Do not hesitate to report a bug. It is +better to fill a report twice than never. However, this chapter includes +recommendations on how to file good bug reports. + +For the impatient: + +_* Always check first the image status updates on our homepage at +http://live-systems.org/ for known issues. + +_* Before submitting a bug report always try to reproduce the bug with the +*{most recent versions}* of the branch of live-build, live-boot, live-config +and live-tools that you're using (like the newest 4.x version of live-build +if you're using live-build 4). + +_* Try to give *{as specific information as possible}* about the bug. This +includes (at least) the version of live-build, live-boot, live-config, and +live-tools used and the distribution of the live system you are building. + +2~ Known issues + +Since Debian *{testing}* and Debian *{unstable}* distributions are moving +targets, when you specify either of them as the target system distribution, +a successful build may not always be possible. + +% FIXME: + +If this causes too much difficulty for you, do not build a system based on +*{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always +defaults to the *{stable}* release. + +Currently known issues are listed under the section 'status' on our homepage +at http://live-systems.org/. + +It is out of the scope of this manual to train you to correctly identify and +fix problems in packages of the development distributions, however, there +are two things you can always try: If a build fails when the target +distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work +either, revert to *{testing}* and pin the newer version of the failing +package from *{unstable}* (see {APT pinning}#apt-pinning for details). + +2~ Rebuild from scratch + +To ensure that a particular bug is not caused by an uncleanly built system, +please always rebuild the whole live system from scratch to see if the bug +is reproducible. + +2~ Use up-to-date packages + +Using outdated packages can cause significant problems when trying to +reproduce (and ultimately fix) your problem. Make sure your build system is +up-to-date and any packages included in your image are up-to-date as well. + +2~collect-information Collect information + +Please provide enough information with your report. Include, at least, the +exact version of live-build where the bug is encountered and the steps to +reproduce it. Please use your common sense and provide any other relevant +information if you think that it might help in solving the problem. + +To make the most out of your bug report, we require at least the following +information: + +_* Architecture of the host system + +_* Distribution of the host system + +_* Version of live-build on the host system + +_* Version of /{debootstrap}/ on the host system + +_* Architecture of the live system + +_* Distribution of the live system + +_* Version of live-boot on the live system + +_* Version of live-config on the live system + +_* Version of live-tools on the live system + +You can generate a log of the build process by using the #{tee}# command. We +recommend doing this automatically with an #{auto/build}# script (see +{Managing a configuration}#managing-a-configuration for details). + +code{ + + # lb build 2>&1 | tee build.log + +}code + +At boot time, live-boot and live-config store their logfiles in +#{/var/log/live/}#. Check them for error messages. + +Additionally, to rule out other errors, it is always a good idea to tar up +your #{config/}# directory and upload it somewhere (do *{not}* send it as an +attachment to the mailing list), so that we can try to reproduce the errors +you encountered. If this is difficult (e.g. due to size) you can use the +output of #{lb config --dump}# which produces a summary of your config tree +(i.e. lists files in subdirectories of #{config/}# but does not include +them). + +Remember to send in any logs that were produced with English locale +settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or +#{LC_ALL=en_US}#. + +2~ Isolate the failing case if possible + +If possible, isolate the failing case to the smallest possible change that +breaks. It is not always easy to do this so if you cannot manage it for your +report, do not worry. However, if you plan your development cycle well, +using small enough change sets per iteration, you may be able to isolate the +problem by constructing a simpler 'base' configuration that closely matches +your actual configuration plus just the broken change set added to it. If +you have a hard time sorting out which of your changes broke, it may be that +you are including too much in each change set and should develop in smaller +increments. + +2~ Use the correct package to report the bug against + +If you do not know what component is responsible for the bug or if the bug +is a general bug concerning live systems, you can fill a bug against the +debian-live pseudo-package. + +However, we would appreciate it if you try to narrow it down according to +where the bug appears. + +3~ At build time while bootstrapping + +live-build first bootstraps a basic Debian system with /{debootstrap}/. If a +bug appears here, check if the error is related to a specific Debian package +(most likely), or if it is related to the bootstrapping tool itself. + +In both cases, this is not a bug in the live system, but rather in Debian +itself and probably we cannot fix it directly. Please report such a bug +against the bootstrapping tool or the failing package. + +3~ At build time while installing packages + +live-build installs additional packages from the Debian archive and +depending on the Debian distribution used and the daily archive state, it +can fail. If a bug appears here, check if the error is also reproducible on +a normal system. + +If this is the case, this is not a bug in the live system, but rather in +Debian - please report it against the failing package. Running +/{debootstrap}/ separately from the Live system build or running #{lb +bootstrap --debug}# will give you more information. + +Also, if you are using a local mirror and/or any sort of proxy and you are +experiencing a problem, please always reproduce it first by bootstrapping +from an official mirror. + +3~ At boot time + +If your image does not boot, please report it to the mailing list together +with the information requested in {Collect +information}#collect-information. Do not forget to mention, how/when the +image failed exactly, whether using virtualization or real hardware. If you +are using a virtualization technology of any kind, please always run it on +real hardware before reporting a bug. Providing a screenshot of the failure +is also very helpful. + +3~ At run time + +If a package was successfully installed, but fails while actually running +the Live system, this is probably a bug in the live system. However: + +2~ Do the research + +Before filing the bug, please search the web for the particular error +message or symptom you are getting. As it is highly unlikely that you are +the only person experiencing a particular problem. There is always a chance +that it has been discussed elsewhere and a possible solution, patch, or +workaround has been proposed. + +You should pay particular attention to the live systems mailing list, as +well as the homepage, as these are likely to contain the most up-to-date +information. If such information exists, always include the references to it +in your bug report. + +In addition, you should check the current bug lists for live-build, +live-boot, live-config and live-tools to see whether something similar has +already been reported. + +2~ Where to report bugs + +The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For +information on how to use the system, please see +https://bugs.debian.org/. You can also submit the bugs by using the +#{reportbug}# command from the package with the same name. + +In general, you should report build time errors against the live-build +package, boot time errors against live-boot, and run time errors against +live-config. If you are unsure of which package is appropriate or need more +help before submitting a bug report, please report it against the +debian-live pseudo-package. We will then take care about it and reassign it +where appropriate. + +Please note that bugs found in distributions derived from Debian (such as +Ubuntu and others) should *{not}* be reported to the Debian BTS unless they +can be also reproduced on a Debian system using official Debian packages. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/project_coding-style.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/project_coding-style.ssi new file mode 100644 index 0000000..2adba20 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/project_coding-style.ssi @@ -0,0 +1,149 @@ +:B~ Coding Style + +1~coding-style Coding Style + +This chapter documents the coding style used in live systems. + +2~ Compatibility + +_* Don't use syntax or semantics that are unique to the Bash shell. For +example, the use of array constructs. + +_* Only use the POSIX subset - for example, use $(foo) over `foo`. + +_* You can check your scripts with 'sh -n' and 'checkbashisms'. + +_* Make sure all shell code runs with 'set -e'. + +2~ Indenting + +_* Always use tabs over spaces. + +2~ Wrapping + +_* Generally, lines are 80 chars at maximum. + +_* Use the "Linux style" of line breaks: + +Bad: + +code{ + + if foo; then + bar + fi + +}code + +Good: + +code{ + + if foo + then + bar + fi + +}code + +_* The same holds for functions: + +Bad: + +code{ + + Foo () { + bar + } + +}code + +Good: + +code{ + + Foo () + { + bar + } + +}code + +2~ Variables + +_* Variables are always in capital letters. + +_* Variables used in live-build always start with #{LB_}# prefix. + +_* Internal temporary variables in live-build should start with the +#{\_LB_}# prefix. + +_* Local variables start with live-build #{\_\_LB_}# prefix. + +_* Variables in connection to a boot parameter in live-config start with +#{LIVE_}#. + +_* All other variables in live-config start with #{_}# prefix. + +_* Use braces around variables; e.g. write #{${FOO}}# instead of #{$FOO}#. + +_* Always protect variables with quotes to respect potential whitespaces: +write #{"${FOO}"}# not #{${FOO}}#. + +_* For consistency reasons, always use quotes when assigning values to +variables: + +Bad: + +code{ + + FOO=bar + +}code + +Good: + +code{ + + FOO="bar" + +}code + +_* If multiple variables are used, quote the full expression: + +Bad: + +code{ + + if [ -f "${FOO}"/foo/"${BAR}"/bar ] + then + foobar + fi + +}code + +Good: + +code{ + + if [ -f "${FOO}/foo/${BAR}/bar" ] + then + foobar + fi + +}code + +2~ Miscellaneous + +_* Use "#{|}#" (without the surround quotes) as a separator in calls to sed, +e.g. "#{sed -e 's|foo|bar|'}#" (without ""). + +_* Don't use the #{test}# command for comparisons or tests, use "#{[}#" +"#{]}#" (without ""); e.g. "#{if [ -x /bin/foo ]; ...}#" and not "#{if test +-x /bin/foo; ...}#". + +_* Use #{case}# wherever possible over #{test}#, as it's easier to read and +faster in execution. + +_* Use capitalized names for functions to limit messing with the users +environment. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/project_contributing.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/project_contributing.ssi new file mode 100644 index 0000000..08ce7a5 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/project_contributing.ssi @@ -0,0 +1,114 @@ +:B~ Contributing to the project + +1~contributing-to-project Contributing to the project + +When submitting a contribution, please clearly identify its copyright holder +and include any applicable licensing statement. Note that to be accepted, +the contribution must be licensed under the same license as the rest of the +documents, namely, GPL version 3 or later. + +Contributions to the project, such as translations and patches, are greatly +welcome. Anyone can directly commit to the repositories, however, we ask you +to send bigger changes to the mailing list to discuss them first. See the +section {Contact}#contact for more information. + +The ${project} uses Git as version control system and source code +management. As explained in {Git repositories}#git-repositories there are +two main development branches: *{debian}* and *{debian-next}*. Everybody can +commit to the debian-next branches of the live-boot, live-build, +live-config, live-images, live-manual and live-tools repositories. + +However, there are certain restrictions. The server will reject: + +_* Non fast-forward pushes. + +_* Merge commits. + +_* Adding or removing tags or branches. + +Even though all commits might be revised, we ask you to use your common +sense and make good commits with good commit messages. + +_* Write commit messages that consist of complete, meaningful sentences in +English, starting with a capital letter and ending with a full +stop. Usually, these will start with the form +"Fixing/Adding/Removing/Correcting/Translating/...". + +_* Write good commit messages. The first line must be an accurate summary of +the contents of the commit which will be included in the changelog. If you +need to make some further explanations, write them below leaving a blank +line after the first one and then another blank line after each +paragraph. Lines of paragraphs should not exceed 80 characters in length. + +_* Commit atomically, this is to say, do not mix unrelated things in the +same commit. Make one different commit for each change you make. + +2~ Making changes + +In order to push to the repositories, you must follow the following +procedure. Here we use live-manual as an example so replace it with the name +of the repository you want to work with. For detailed information on how to +edit live-manual see {Contributing to this document}#how-to-contribute. + +_* Fetch the public commit key: + +code{ + + $ mkdir -p ~/.ssh/keys + $ wget http://live-systems.org/other/keys/git@live-systems.org -O ~/.ssh/keys/git@live-systems.org + $ wget http://live-systems.org/other/keys/git@live-systems.org.pub -O ~/.ssh/keys/git@live-systems.org.pub + $ chmod 0600 ~/.ssh/keys/git@live-systems.org* + +}code + +_* Adaugati urmatoarea sectiuna la openssh-client config: + +code{ + + $ cat >> ~/.ssh/config << EOF + Host live-systems.org + Hostname live-systems.org + User git + IdentitiesOnly yes + IdentityFile ~/.ssh/keys/git@live-systems.org + EOF + +}code + +_* Check out a clone of live-manual through ssh: + +code{ + + $ git clone git@live-systems.org:/live-manual.git + $ cd live-manual && git checkout debian-next + +}code + +_* Make sure you have Git author and email set: + +code{ + + $ git config user.name "John Doe" + $ git config user.email john@example.org + +}code + +*{Important:}* Remember that you should commit any changes on the *{debian-next}* branch. + +_* Make your changes. In this example you would first write a new section +dealing with applying patches and then prepare to commit adding the files +and writing your commit message like this: + +code{ + + $ git commit -a -m "Adding a section on applying patches." + +}code + +_* Primite commit-ul la server: + +code{ + + $ git push + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/project_git.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/project_git.ssi new file mode 100644 index 0000000..fd15acd --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/project_git.ssi @@ -0,0 +1,87 @@ +:B~ Git repositories + +1~git-repositories Git repositories + +The list of all the available repositories of the ${project} can be found at +http://live-systems.org/gitweb/. The project's git URLs have the form: +#{protocol://live-systems.org/git/repository}#. Thus, in order to clone +live-manual read-only, launch: + +code{ + + $ git clone git://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone https://live-systems.org/git/live-manual.git + +}code + +Or, + +code{ + + $ git clone http://live-systems.org/git/live-manual.git + +}code + +The cloning addresses with write permission have the form: +#{git@live-systems.org:/repository}#. + +So, again, to clone live-manual over ssh you must type: + +code{ + + $ git clone git@live-systems.org:live-manual.git + +}code + +The git tree is made up of several different branches. The *{debian}* and +the *{debian-next}* branches are particularly noteworthy because they +contain the actual work that will eventually be included in each new +release. + +After cloning any of the existing repositories, you will be on the +*{debian}* branch. This is appropriate to take a look at the state of the +project's latest release but before starting work it is crucial to switch to +the *{debian-next}* branch. To do so: + +code{ + + $ git checkout debian-next + +}code + +The *{debian-next}* branch, which is not always fast-forward, is where all +the changes are committed first before being merged into the *{debian}* +branch. To make an analogy, it is like a testing ground. If you are working +on this branch and need to pull, you will have to do a #{git pull --rebase}# +so that your local modifications are staged while pulling from the server +and then your changes will be put on top of it all. + +2~ Handling multiple repositories + +If you intend to clone several of the live systems repositories and want to +switch to the *{debian-next}* branch right away to check the latest code, +write a patch or contribute with a translation you ought to know that the +git server provides a #{mrconfig}# file to ease the handling of multiple +repositories. In order to use it you need to install the /{mr}/ package and +after that, launch: + +code{ + + $ mr bootstrap http://live-systems.org/other/mr/mrconfig + +}code + +This command will automatically clone and checkout to the *{debian-next}* +branch the development repositories of the Debian packages produced by the +project. These include, among others, the live-images repository, which +contains the configurations used for the prebuilt images that the project +publishes for general use. For more information on how to use this +repository, see {Clone a configuration published via +Git}#clone-configuration-via-git diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/project_procedures.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/project_procedures.ssi new file mode 100644 index 0000000..f6122d3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/project_procedures.ssi @@ -0,0 +1,99 @@ +:B~ Procedures + +1~procedures Procedures + +This chapter documents the procedures within the ${project} for various +tasks that need cooperation with other teams in Debian. + +2~ Major Releases + +Releasing a new stable major version of Debian includes a lot of different +teams working together to make it happen. At some point, the Live team comes +in and builds live system images. The requirements to do this are: + +_* A mirror containing the released versions for the debian and +debian-security archives which the debian-live buildd can access. + +_* The names of the image need to be known +(e.g. debian-live-VERSION-ARCH-FLAVOUR.iso). + +_* The data from debian-cd needs to be synced (udeb exclude lists). + +_* Images are built and mirrored on cdimage.debian.org. + +2~ Point Releases + +_* Again, we need updated mirrors of debian and debian-security. + +_* Images are built and mirrored on cdimage.debian.org. + +_* Send announcement mail. + +3~ Last Point Release of a Debian Release + +Remember to adjust both chroot and binary mirrors when building the last set +of images for a Debian release after it has been moved away from +ftp.debian.org to archive.debian.org. That way, old prebuilt live images are +still useful without user modifications. + +3~ Point release announcement template + +An announcement mail for point releases can be generated using the template +below and the following command: + +code{ + + $ sed \ + -e 's|@MAJOR@|9.0|g' \ + -e 's|@MINOR@|9.0.1|g' \ + -e 's|@CODENAME@|stretch|g' \ + -e 's|@ANNOUNCE@|2017/msgXXXXX.html|g' + +}code + +Please check the mail carefully before sending and pass it to others for +proof-reading. + +code{ + + Updated Live @MAJOR@: @MINOR@ released + + The Live Systems Project is pleased to announce the @MINOR@ update of the + Live images for the stable distribution Debian @MAJOR@ (codename "@CODENAME@"). + + The images are available for download at: + + <http://live-systems.org/cdimage/release/current/> + + and later at: + + <http://cdimage.debian.org/cdimage/release/current-live/> + + This update includes the changes of the Debian @MINOR@ release: + + <https://lists.debian.org/debian-announce/@ANNOUNCE@> + + Additionally it includes the following Live-specific changes: + + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [INSERT LIVE-SPECIFIC CHANGE HERE] + * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] + + About Live Systems + ------------------ + The Live Systems Project produces the tools used to build official + live systems and the official live images themselves for Debian. + + About Debian + ------------ + The Debian Project is an association of Free Software developers who + volunteer their time and effort in order to produce the completely free + operating system Debian. + + Contact Information + ------------------- + For further information, please visit the Live Systems web pages at + <http://live-systems.org/>, or contact the Live Systems team at + <debian-live@lists.debian.org>. + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_basics.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_basics.ssi new file mode 100644 index 0000000..92371a8 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_basics.ssi @@ -0,0 +1,626 @@ +:B~ The basics + +1~the-basics The basics + +This chapter contains a brief overview of the build process and instructions +for using the three most commonly used image types. The most versatile image +type, #{iso-hybrid}#, may be used on a virtual machine, optical medium or +USB portable storage device. In certain special cases, as explained later, +the #{hdd}# type may be more suitable. The chapter includes detailed +instructions for building and using a #{netboot}# type image, which is a bit +more involved due to the setup required on the server. This is an slightly +advanced topic for anyone who is not already familiar with netbooting, but +it is included here because once the setup is done, it is a very convenient +way to test and deploy images for booting on the local network without the +hassle of dealing with image media. + +The section finishes with a quick introduction to {webbooting}#webbooting +which is, perhaps, the easiest way of using different images for different +purposes, switching from one to the other as needed using the internet as a +means. + +Throughout the chapter, we will often refer to the default filenames +produced by live-build. If you are {downloading a prebuilt +image}#downloading-prebuilt-images instead, the actual filenames may vary. + +2~what-is-live What is a live system? + +A live system usually means an operating system booted on a computer from a +removable medium, such as a CD-ROM or USB stick, or from a network, ready to +use without any installation on the usual drive(s), with auto-configuration +done at run time (see {Terms}#terms). + +With live systems, it's an operating system, built for one of the supported +architectures (currently amd64 and i386). It is made from the following +parts: + +_* *{Linux kernel image}*, usually named #{vmlinuz*}# + +_* *{Initial RAM disk image (initrd)}*: a RAM disk set up for the Linux +boot, containing modules possibly needed to mount the System image and some +scripts to do it. + +_* *{System image}*: The operating system's filesystem image. Usually, a +SquashFS compressed filesystem is used to minimize the live system image +size. Note that it is read-only. So, during boot the live system will use a +RAM disk and 'union' mechanism to enable writing files within the running +system. However, all modifications will be lost upon shutdown unless +optional persistence is used (see {Persistence}#persistence). + +_* *{Bootloader}*: A small piece of code crafted to boot from the chosen +medium, possibly presenting a prompt or menu to allow selection of +options/configuration. It loads the Linux kernel and its initrd to run with +an associated system filesystem. Different solutions can be used, depending +on the target medium and format of the filesystem containing the previously +mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, +syslinux for HDD or USB drive booting from a VFAT partition, extlinux for +ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 +partitions, etc. + +You can use live-build to build the system image from your specifications, +set up a Linux kernel, its initrd, and a bootloader to run them, all in one +medium-dependant format (ISO9660 image, disk image, etc.). + +2~downloading-prebuilt-images Downloading prebuilt images + +While the focus of this manual is developing and building your own live +images, you may simply wish to try one of our prebuilt images, either as an +introduction to their use or instead of building your own. These images are +built using our {live-images git repository}#clone-configuration-via-git and +official stable releases are published at +https://www.debian.org/CD/live/. In addition, older and upcoming releases, +and unofficial images containing non-free firmware and drivers are available +at http://live-systems.org/cdimage/release/. + +2~using-web-builder Using the web live image builder + +As a service to the community, we run a web-based live image builder service +at http://live-systems.org/build/. This site is maintained on a best effort +basis. That is, although we strive to keep it up-to-date and operational at +all times, and do issue notices for significant operational outages, we +cannot guarantee 100% availability or fast image building, and the service +may occasionally have issues that take some time to resolve. If you have +problems or questions about the service, please {contact us}#contact, +providing us with the link to your build. + +3~ Web builder usage and caveats + +The web interface currently makes no provision to prevent the use of invalid +combinations of options, and in particular, where changing an option would +normally (i.e. using live-build directly) change defaults of other options +listed in the web form, the web builder does not change these defaults. Most +notably, if you change #{--architectures}# from the default #{i386}# to +#{amd64}#, you must change the corresponding option #{--linux-flavours}# +from the default #{586}# to #{amd64}#. See the #{lb_config}# man page for +the version of live-build installed on the web builder for more details. The +version number of live-build is listed at the bottom of the web builder +page. + +The time estimate given by the web builder is a crude estimate only and may +not reflect how long your build actually takes. Nor is the estimate updated +once it is displayed. Please be patient. Do not refresh the page you land on +after submitting the build, as this will resubmit a new build with the same +parameters. You should {contact us}#contact if you don't receive +notification of your build only once you are certain you've waited long +enough and verified the notification e-mail did not get caught by your own +e-mail spam filter. + +The web builder is limited in the kinds of images it can build. This keeps +it simple and efficient to use and maintain. If you would like to make +customizations that are not provided for by the web interface, the rest of +this manual explains how to build your own images using live-build. + +2~building-iso-hybrid First steps: building an ISO hybrid image + +Regardless of the image type, you will need to perform the same basic steps +to build an image each time. As a first example, create a build directory, +change to that directory and then execute the following sequence of +live-build commands to create a basic ISO hybrid image containing a default +live system without X.org. It is suitable for burning to CD or DVD media, +and also to copy onto a USB stick. + +The name of the working directory is absolutely up to you, but if you take a +look at the examples used throughout live-manual, it is a good idea to use a +name that helps you identify the image you are working with in each +directory, especially if you are working or experimenting with different +image types. In this case you are going to build a default system so let's +call it, for example, live-default. + +code{ + + $ mkdir live-default && cd live-default + +}code + +Then, run the #{lb config}# command. This will create a "config/" hierarchy +in the current directory for use by other commands: + +code{ + + $ lb config + +}code + +No parameters are passed to these commands, so defaults for all of their +various options will be used. See {The lb config command}#lb-config for more +details. + +Now that the "config/" hierarchy exists, build the image with the #{lb +build}# command: + +code{ + + # lb build + +}code + +This process can take a while, depending on the speed of your computer and +your network connection. When it is complete, there should be a +#{live-image-i386.hybrid.iso}# image file, ready to use, in the current +directory. + +*{Note:}* If you are building on an amd64 system the name of the resulting image will be #{live-image-amd64.hybrid.iso}#. Keep in mind this naming convention throughout the manual. + +2~using-iso-hybrid Using an ISO hybrid live image + +After either building or downloading an ISO hybrid image, which can be +obtained at https://www.debian.org/CD/live/, the usual next step is to +prepare your medium for booting, either CD-R(W) or DVD-R(W) optical media or +a USB stick. + +3~burning-iso-image Burning an ISO image to a physical medium + +Burning an ISO image is easy. Just install /{xorriso}/ and use it from the +command-line to burn the image. For instance: + +code{ + + # apt-get install xorriso + $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed live-image-i386.hybrid.iso + +}code + +3~copying-iso-hybrid-to-usb Copying an ISO hybrid image to a USB stick + +ISO images prepared with #{xorriso}#, can be simply copied to a USB stick +with the #{cp}# program or an equivalent. Plug in a USB stick with a size +large enough for your image file and determine which device it is, which we +hereafter refer to as #{${USBSTICK}}#. This is the device file of your key, +such as #{/dev/sdb}#, not a partition, such as #{/dev/sdb1}#! You can find +the right device name by looking in #{dmesg}#'s output after plugging in the +stick, or better yet, #{ls -l /dev/disk/by-id}#. + +Once you are certain you have the correct device name, use the #{cp}# +command to copy the image to the stick. *{This will definitely overwrite +any previous contents on your stick!}* + +code{ + + $ cp live-image-i386.hybrid.iso ${USBSTICK} + $ sync + +}code + +*{Note:}* The /{sync}/ command is useful to ensure that all the data, which is stored in memory by the kernel while copying the image, is written to the USB stick. + +3~using-usb-extra-space Using the space left on a USB stick + +After copying the #{live-image-i386.hybrid.iso}# to a USB stick, the first +partition on the device will be filled up by the live system. To use the +remaining free space, use a partitioning tool such as /{gparted}/ or +/{parted}/ to create a new partition on the stick. + +code{ + + # gparted ${USBSTICK} + +}code + +After the partition is created, where #{${PARTITION}}# is the name of the +partition, such as #{/dev/sdb2}#, you have to create a filesystem on it. One +possible choice would be ext4. + +code{ + + # mkfs.ext4 ${PARTITION} + +}code + +*{Note:}* If you want to use the extra space with Windows, apparently that OS cannot normally access any partitions but the first. Some solutions to this problem have been discussed on our {mailing list}#contact, but it seems there are no easy answers. + +*{Remember: Every time you install a new live-image-i386.hybrid.iso on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image, so back up your extra partition first to restore again after updating the live image.}* + +3~booting-live-medium Booting the live medium + +The first time you boot your live medium, whether CD, DVD, USB key, or PXE +boot, some setup in your computer's BIOS may be needed first. Since BIOSes +vary greatly in features and key bindings, we cannot get into the topic in +depth here. Some BIOSes provide a key to bring up a menu of boot devices at +boot time, which is the easiest way if it is available on your +system. Otherwise, you need to enter the BIOS configuration menu and change +the boot order to place the boot device for the live system before your +normal boot device. + +Once you've booted the medium, you are presented with a boot menu. If you +just press enter here, the system will boot using the default entry, +#{Live}# and default options. For more information about boot options, see +the "help" entry in the menu and also the live-boot and live-config man +pages found within the live system. + +Assuming you've selected #{Live}# and booted a default desktop live image, +after the boot messages scroll by, you should be automatically logged into +the #{user}# account and see a desktop, ready to use. If you have booted a +console-only image, such as a #{standard}# flavour {prebuilt +image}#downloading-prebuilt-images, you should be automatically logged in on +the console to the #{user}# account and see a shell prompt, ready to use. + +2~using-virtual-machine Using a virtual machine for testing + +It can be a great time-saver for the development of live images to run them +in a virtual machine (VM). This is not without its caveats: + +_* Running a VM requires enough RAM for both the guest OS and the host and a +CPU with hardware support for virtualization is recommended. + +_* There are some inherent limitations to running on a VM, e.g. poor video +performance, limited choice of emulated hardware. + +_* When developing for specific hardware, there is no substitute for running +on the hardware itself. + +_* Occasionally there are bugs that relate only to running in a VM. When in +doubt, test your image directly on the hardware. + +Provided you can work within these constraints, survey the available VM +software and choose one that is suitable for your needs. + +3~testing-iso-with-qemu Testing an ISO image with QEMU + +The most versatile VM in Debian is QEMU. If your processor has hardware +support for virtualization, use the /{qemu-kvm}/ package; the /{qemu-kvm}/ +package description briefly lists the requirements. + +First, install /{qemu-kvm}/ if your processor supports it. If not, install +/{qemu}/, in which case the program name is #{qemu}# instead of #{kvm}# in +the following examples. The /{qemu-utils}/ package is also valuable for +creating virtual disk images with #{qemu-img}#. + +code{ + + # apt-get install qemu-kvm qemu-utils + +}code + +Booting an ISO image is simple: + +code{ + + $ kvm -cdrom live-image-i386.hybrid.iso + +}code + +See the man pages for more details. + +3~testing-iso-with-virtualbox Testing an ISO image with VirtualBox + +In order to test the ISO with /{virtualbox}/: + +code{ + + # apt-get install virtualbox virtualbox-qt virtualbox-dkms + $ virtualbox + +}code + +Create a new virtual machine, change the storage settings to use +#{live-image-i386.hybrid.iso}# as the CD/DVD device, and start the machine. + +*{Note:}* For live systems containing X.org that you want to test with /{virtualbox}/, you may wish to include the VirtualBox X.org driver package, /{virtualbox-guest-dkms}/ and /{virtualbox-guest-x11}/, in your live-build configuration. Otherwise, the resolution is limited to 800x600. + +code{ + + $ echo "virtualbox-guest-dkms virtualbox-guest-x11" >> config/package-lists/my.list.chroot + +}code + +In order to make the dkms package work, also the kernel headers for the +kernel flavour used in your image need to be installed. Instead of manually +listing the correct /{linux-headers}/ package in above created package list, +the selection of the right package can be done automatically by live-build. + +code{ + + $ lb config --linux-packages "linux-image linux-headers" + +}code + +2~using-hdd-image Building and using an HDD image + +Building an HDD image is similar to an ISO hybrid one in all respects except +you specify #{-b hdd}# and the resulting filename is #{live-image-i386.img}# +which cannot be burnt to optical media. It is suitable for booting from USB +sticks, USB hard drives, and various other portable storage +devices. Normally, an ISO hybrid image can be used for this purpose instead, +but if you have a BIOS which does not handle hybrid images properly, you +need an HDD image. + +*{Note:}* if you created an ISO hybrid image with the previous example, you will need to clean up your working directory with the #{lb clean}# command (see {The lb clean command}#lb-clean): + +code{ + + # lb clean --binary + +}code + +Run the #{lb config}# command as before, except this time specifying the HDD +image type: + +code{ + + $ lb config -b hdd + +}code + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +When the build finishes, a #{live-image-i386.img}# file should be present in +the current directory. + +The generated binary image contains a VFAT partition and the syslinux +bootloader, ready to be directly written on a USB device. Once again, using +an HDD image is just like using an ISO hybrid one on USB. Follow the +instructions in {Using an ISO hybrid live image}#using-iso-hybrid, except +use the filename #{live-image-i386.img}# instead of +#{live-image-i386.hybrid.iso}#. + +Likewise, to test an HDD image with Qemu, install /{qemu}/ as described +above in {Testing an ISO image with QEMU}#testing-iso-with-qemu. Then run +#{kvm}# or #{qemu}#, depending on which version your host system needs, +specifying #{live-image-i386.img}# as the first hard drive. + +code{ + + $ kvm -hda live-image-i386.img + +}code + +2~building-netboot-image Building a netboot image + +The following sequence of commands will create a basic netboot image +containing a default live system without X.org. It is suitable for booting +over the network. + +*{Note:}* if you performed any previous examples, you will need to clean up your working directory with the #{lb clean}# command: + +code{ + + # lb clean + +}code + +In this specific case, a #{lb clean --binary}# would not be enough to clean +up the necessary stages. The cause for this is that in netboot setups, a +different initramfs configuration needs to be used which live-build performs +automatically when building netboot images. Since the initramfs creation +belongs to the chroot stage, switching to netboot in an existing build +directory means to rebuild the chroot stage too. Therefore, #{lb clean}# +(which will remove the chroot stage, too) needs to be used. + +Run the #{lb config}# command as follows to configure your image for +netbooting: + +code{ + + $ lb config -b netboot --net-root-path "/srv/debian-live" --net-root-server "192.168.0.2" + +}code + +In contrast with the ISO and HDD images, netbooting does not, itself, serve +the filesystem image to the client, so the files must be served via +NFS. Different network filesystems can be chosen through lb config. The +#{--net-root-path}# and #{--net-root-server}# options specify the location +and server, respectively, of the NFS server where the filesystem image will +be located at boot time. Make sure these are set to suitable values for your +network and server. + +Now build the image with the #{lb build}# command: + +code{ + + # lb build + +}code + +In a network boot, the client runs a small piece of software which usually +resides on the EPROM of the Ethernet card. This program sends a DHCP request +to get an IP address and information about what to do next. Typically, the +next step is getting a higher level bootloader via the TFTP protocol. That +could be pxelinux, GRUB, or even boot directly to an operating system like +Linux. + +For example, if you unpack the generated #{live-image-i386.netboot.tar}# +archive in the #{/srv/debian-live}# directory, you'll find the filesystem +image in #{live/filesystem.squashfs}# and the kernel, initrd and pxelinux +bootloader in #{tftpboot/}#. + +We must now configure three services on the server to enable netbooting: the +DHCP server, the TFTP server and the NFS server. + +3~ DHCP server + +We must configure our network's DHCP server to be sure to give an IP address +to the netbooting client system, and to advertise the location of the PXE +bootloader. + +Here is an example for inspiration, written for the ISC DHCP server +#{isc-dhcp-server}# in the #{/etc/dhcp/dhcpd.conf}# configuration file: + +code{ + + # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server + + ddns-update-style none; + + option domain-name "example.org"; + option domain-name-servers ns1.example.org, ns2.example.org; + + default-lease-time 600; + max-lease-time 7200; + + log-facility local7; + + subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.1 192.168.0.254; + filename "pxelinux.0"; + next-server 192.168.0.2; + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.0.255; + option routers 192.168.0.1; +} + +}code + +3~ TFTP server + +This serves the kernel and initial ramdisk to the system at run time. + +You should install the /{tftpd-hpa}/ package. It can serve all files +contained inside a root directory, usually #{/srv/tftp}#. To let it serve +files inside #{/srv/debian-live/tftpboot}#, run as root the following +command: + +code{ + + # dpkg-reconfigure -plow tftpd-hpa + +}code + +and fill in the new tftp server directory when being asked about it. + +3~ NFS server + +Once the guest computer has downloaded and booted a Linux kernel and loaded +its initrd, it will try to mount the Live filesystem image through a NFS +server. + +You need to install the /{nfs-kernel-server}/ package. + +Then, make the filesystem image available through NFS by adding a line like +the following to #{/etc/exports}#: + +code{ + + /srv/debian-live *(ro,async,no_root_squash,no_subtree_check) + +}code + +and tell the NFS server about this new export with the following command: + +code{ + + # exportfs -rv + +}code + +Setting up these three services can be a little tricky. You might need some +patience to get all of them working together. For more information, see the +syslinux wiki at http://www.syslinux.org/wiki/index.php/PXELINUX or the +Debian Installer Manual's TFTP Net Booting section at +http://d-i.alioth.debian.org/manual/en.i386/ch04s05.html. They might help, +as their processes are very similar. + +3~ Netboot testing HowTo + +Netboot image creation is made easy with live-build, but testing the images +on physical machines can be really time consuming. + +To make our life easier, we can use virtualization. + +3~ Qemu + +_* Install /{qemu}/, /{bridge-utils}/, /{sudo}/. + +Edit #{/etc/qemu-ifup}#: + +code{ + + #!/bin/sh + sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 + echo "Executing /etc/qemu-ifup" + echo "Bringing up $1 for bridged mode..." + sudo /sbin/ifconfig $1 0.0.0.0 promisc up + echo "Adding $1 to br0..." + sudo /usr/sbin/brctl addif br0 $1 + sleep 2 + +}code + +Get, or build a #{grub-floppy-netboot}#. + +Launch #{qemu}# with "#{-net nic,vlan=0 -net tap,vlan=0,ifname=tun0}#" + +2~webbooting Webbooting + +Webbooting is a convenient way of retrieving and booting live systems using +the internet as a means. The requirements for webbooting are very few. On +the one hand, you need a medium with a bootloader, an initial ramdisk and a +kernel. On the other hand, a web server to store the squashfs files which +contain the filesystem. + +3~ Getting the webboot files + +As usual, you can build the images yourself or use the prebuilt files, which +are available on the project's homepage at http://live-systems.org/. Using +prebuilt images would be handy for doing initial testing until one can fine +tune their own needs. If you have built a live image you will find the files +needed for webbooting in the build directory under #{binary/live/}#. The +files are called #{vmlinuz}#, #{initrd.img}# and #{filesystem.squashfs}#. + +It is also possible to extract those files from an already existing iso +image. In order to achieve that, loopback mount the image as follows: + +code{ + + # mount -o loop image.iso /mnt + +}code + +The files are to be found under the #{live/}# directory. In this specific +case, it would be #{/mnt/live/}#. This method has the disadvantage that you +need to be root to be able to mount the image. However, it has the advantage +that it is easily scriptable and thus, easily automatized. + +But undoubtedly, the easiest way of extracting the files from an iso image +and uploading it to the web server at the same time, is using the midnight +commander or /{mc}/. If you have the /{genisoimage}/ package installed, the +two-pane file manager allows you to browse the contents of an iso file in +one pane and upload the files via ftp in the other pane. Even though this +method requires manual work, it does not require root privileges. + +3~ Booting webboot images + +While some users will prefer virtualization to test webbooting, we refer to +real hardware here to match the following possible use case which should +only be considered as an example. + +In order to boot a webboot image it is enough to have the components +mentioned above, i.e. #{vmlinuz}# and #{initrd.img}# in a usb stick inside a +directory named #{live/}# and install syslinux as bootloader. Then boot from +the usb stick and type #{fetch=URL/PATH/TO/FILE}# at the boot +options. live-boot will retrieve the squashfs file and store it into +ram. This way, it is possible to use the downloaded compressed filesystem as +a regular live system. For example: + +code{ + + append boot=live components fetch=http://192.168.2.50/images/webboot/filesystem.squashfs + +}code + +*{Use case:}* You have a web server in which you have stored two squashfs files, one which contains a full desktop, like for example gnome, and a standard one. If you need a graphical environment for one machine, you can plug your usb stick in and webboot the gnome image. If you need one of the tools included in the second type of image, perhaps for another machine, you can webboot the standard one. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-binary.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-binary.ssi new file mode 100644 index 0000000..aa7929a --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-binary.ssi @@ -0,0 +1,62 @@ +:B~ Customizing the binary image + +1~customizing-binary Customizing the binary image + +2~ Bootloaders + +live-build uses /{syslinux}/ and some of its derivatives (depending on the +image type) as bootloaders by default. They can be easily customized to suit +your needs. + +In order to use a full theme, copy #{/usr/share/live/build/bootloaders}# +into #{config/bootloaders}# and edit the files in there. If you do not want +to bother modifying all supported bootloader configurations, only providing +a local customized copy of one of the bootloaders, e.g. *{isolinux}* in +#{config/bootloaders/isolinux}# is enough too, depending on your use case. + +When modifying one of the default themes, if you want to use a personalized +background image that will be displayed together with the boot menu, add a +splash.png picture of 640x480 pixels. Then, remove the splash.svg file. + +There are many possibilities when it comes to making changes. For instance, +syslinux derivatives are configured by default with a timeout of 0 (zero) +which means that they will pause indefinitely at their splash screen until +you press a key. + +To modify the boot timeout of a default #{iso-hybrid}# image just edit a +default *{isolinux.cfg}* file specifying the timeout in units of 1/10 +seconds. A modified *{isolinux.cfg}* to boot after five seconds would be +similar to this: + +code{ + + include menu.cfg + default vesamenu.c32 + prompt 0 + timeout 50 + +}code + +2~ ISO metadata + +When creating an ISO9660 binary image, you can use the following options to +add various textual metadata for your image. This can help you easily +identify the version or configuration of an image without booting it. + +_* #{LB_ISO_APPLICATION/--iso-application NAME}#: This should describe the +application that will be on the image. The maximum length for this field is +128 characters. + +_* #{LB_ISO_PREPARER/--iso-preparer NAME}#: This should describe the +preparer of the image, usually with some contact details. The default for +this option is the live-build version you are using, which may help with +debugging later. The maximum length for this field is 128 characters. + +_* #{LB_ISO_PUBLISHER/--iso-publisher NAME}#: This should describe the +publisher of the image, usually with some contact details. The maximum +length for this field is 128 characters. + +_* #{LB_ISO_VOLUME/--iso-volume NAME}#: This should specify the volume ID of +the image. This is used as a user-visible label on some platforms such as +Windows and Apple Mac OS. The maximum length for this field is 32 +characters. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-contents.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-contents.ssi new file mode 100644 index 0000000..821fea4 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-contents.ssi @@ -0,0 +1,135 @@ +:B~ Customizing contents + +1~customizing-contents Customizing contents + +This chapter discusses fine-tuning customization of the live system contents +beyond merely choosing which packages to include. Includes allow you to add +or replace arbitrary files in your live system image, hooks allow you to +execute arbitrary commands at different stages of the build and at boot +time, and preseeding allows you to configure packages when they are +installed by supplying answers to debconf questions. + +2~includes Includes + +While ideally a live system would include files entirely provided by +unmodified packages, it is sometimes convenient to provide or modify some +content by means of files. Using includes, it is possible to add (or +replace) arbitrary files in your live system image. live-build provides two +mechanisms for using them: + +_* Chroot local includes: These allow you to add or replace files to the +chroot/Live filesystem. Please see {Live/chroot local +includes}#live-chroot-local-includes for more information. + +_* Binary local includes: These allow you to add or replace files in the +binary image. Please see {Binary local includes}#binary-local-includes for +more information. + +Please see {Terms}#terms for more information about the distinction between +the "Live" and "binary" images. + +3~live-chroot-local-includes Live/chroot local includes + +Chroot local includes can be used to add or replace files in the chroot/Live +filesystem so that they may be used in the Live system. A typical use is to +populate the skeleton user directory (#{/etc/skel}#) used by the Live system +to create the live user's home directory. Another is to supply configuration +files that can be simply added or replaced in the image without processing; +see {Live/chroot local hooks}#live-chroot-local-hooks if processing is +needed. + +To include files, simply add them to your #{config/includes.chroot}# +directory. This directory corresponds to the root directory #{/}# of the +live system. For example, to add a file #{/var/www/index.html}# in the live +system, use: + +code{ + + $ mkdir -p config/includes.chroot/var/www + $ cp /path/to/my/index.html config/includes.chroot/var/www + +}code + +Your configuration will then have the following layout: + +code{ + + -- config + [...] + |-- includes.chroot + | `-- var + | `-- www + | `-- index.html + [...] + +}code + +Chroot local includes are installed after package installation so that files +installed by packages are overwritten. + +3~binary-local-includes Binary local includes + +To include material such as documentation or videos on the medium filesystem +so that it is accessible immediately upon insertion of the medium without +booting the Live system, you can use binary local includes. This works in a +similar fashion to chroot local includes. For example, suppose the files +#{~/video_demo.*}# are demo videos of the live system described by and +linked to by an HTML index page. Simply copy the material to +#{config/includes.binary/}# as follows: + +code{ + + $ cp ~/video_demo.* config/includes.binary/ + +}code + +These files will now appear in the root directory of the live medium. + +2~hooks Hooks + +Hooks allow commands to be performed in the chroot and binary stages of the +build in order to customize the image. + +3~live-chroot-local-hooks Live/chroot local hooks + +To run commands in the chroot stage, create a hook script with a +#{.hook.chroot}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run in the chroot after the rest of your chroot +configuration has been applied, so remember to ensure your configuration +includes all packages and files your hook needs in order to run. See the +example chroot hook scripts for various common chroot customization tasks +provided in #{/usr/share/doc/live-build/examples/hooks}# which you can copy +or symlink to use them in your own configuration. + +3~boot-time-hooks Boot-time hooks + +To execute commands at boot time, you can supply live-config hooks as +explained in the "Customization" section of its man page. Examine +live-config's own hooks provided in #{/lib/live/config/}#, noting the +sequence numbers. Then provide your own hook prefixed with an appropriate +sequence number, either as a chroot local include in +#{config/includes.chroot/lib/live/config/}#, or as a custom package as +discussed in {Installing modified or third-party +packages}#installing-modified-or-third-party-packages. + +3~ Binary local hooks + +To run commands in the binary stage, create a hook script with a +#{.hook.binary}# suffix containing the commands in the #{config/hooks/}# +directory. The hook will run after all other binary commands are run, but +before binary_checksums, the very last binary command. The commands in your +hook do not run in the chroot, so take care to not modify any files outside +of the build tree, or you may damage your build system! See the example +binary hook scripts for various common binary customization tasks provided +in #{/usr/share/doc/live-build/examples/hooks}# which you can copy or +symlink to use them in your own configuration. + +2~ Preseeding Debconf questions + +Files in the #{config/preseed/}# directory suffixed with #{.cfg}# followed +by the stage (#{.chroot}# or #{.binary}#) are considered to be debconf +preseed files and are installed by live-build using +#{debconf-set-selections}# during the corresponding stage. + +For more information about debconf, please see #{debconf(7)}# in the +/{debconf}/ package. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-installer.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-installer.ssi new file mode 100644 index 0000000..2f3a5a2 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-installer.ssi @@ -0,0 +1,86 @@ +:B~ Customizing Debian Installer + +1~customizing-installer Customizing Debian Installer + +Live system images can be integrated with Debian Installer. There are a +number of different types of installation, varying in what is included and +how the installer operates. + +Please note the careful use of capital letters when referring to the "Debian +Installer" in this section - when used like this we refer explicitly to the +official installer for the Debian system, not anything else. It is often +seen abbreviated to "d-i". + +2~ Types of Debian Installer + +The three main types of installer are: + +*{"Normal" Debian Installer}*: This is a normal live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. Images containing a live system and such an otherwise independent installer are often referred to as "combined images". + +On such images, Debian is installed by fetching and installing .deb packages +using /{debootstrap}/, from local media or some network-based network, +resulting in a default Debian system being installed to the hard disk. + +This whole process can be preseeded and customized in a number of ways; see +the relevant pages in the Debian Installer manual for more information. Once +you have a working preseeding file, live-build can automatically put it in +the image and enable it for you. + +*{"Live" Debian Installer}*: This is a live system image with a separate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. + +Installation will proceed in an identical fashion to the "normal" +installation described above, but at the actual package installation stage, +instead of using /{debootstrap}/ to fetch and install packages, the live +filesystem image is copied to the target. This is achieved with a special +udeb called live-installer. + +After this stage, the Debian Installer continues as normal, installing and +configuring items such as bootloaders and local users, etc. + +*{Note:}* to support both normal and live installer entries in the bootloader of the same live medium, you must disable live-installer by preseeding #{live-installer/enable=false}#. + +*{"Desktop" Debian Installer}*: Regardless of the type of Debian Installer included, #{d-i}# can be launched from the Desktop by clicking on an icon. This is user friendlier in some situations. In order to make use of this, the debian-installer-launcher package needs to be included. + +Note that by default, live-build does not include Debian Installer images in +the images, it needs to be specifically enabled with #{lb config}#. Also, +please note that for the "Desktop" installer to work, the kernel of the live +system must match the kernel #{d-i}# uses for the specified +architecture. For example: + +code{ + + $ lb config --architectures i386 --linux-flavours 586 \ + --debian-installer live + $ echo debian-installer-launcher >> config/package-lists/my.list.chroot + +}code + +2~ Customizing Debian Installer by preseeding + +As described in the Debian Installer Manual, Appendix B at +https://www.debian.org/releases/stable/i386/apb.html, "Preseeding provides a +way to set answers to questions asked during the installation process, +without having to manually enter the answers while the installation is +running. This makes it possible to fully automate most types of installation +and even offers some features not available during normal installations." +This kind of customization is best accomplished with live-build by placing +the configuration in a #{preseed.cfg}# file included in +#{config/includes.installer/}#. For example, to preseed setting the locale +to #{en_US}#: + +code{ + + $ echo "d-i debian-installer/locale string en_US" \ + >> config/includes.installer/preseed.cfg + +}code + +2~ Customizing Debian Installer content + +For experimental or debugging purposes, you might want to include locally +built #{d-i}# component udeb packages. Place these in +#{config/packages.binary/}# to include them in the image. Additional or +replacement files and directories may be included in the installer initrd as +well, in a similar fashion to {Live/chroot local +includes}#live-chroot-local-includes, by placing the material in +#{config/includes.installer/}#. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-overview.ssi new file mode 100644 index 0000000..54ab92c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-overview.ssi @@ -0,0 +1,75 @@ +:B~ Customizing contents + +1~customization-overview Customization overview + +This chapter gives an overview of the various ways in which you may +customize a live system. + +2~ Build time vs. boot time configuration + +Live system configuration options are divided into build-time options which +are options that are applied at build time and boot-time options which are +applied at boot time. Boot-time options are further divided into those +occurring early in the boot, applied by the live-boot package, and those +that happen later in the boot, applied by live-config. Any boot-time option +may be modified by the user by specifying it at the boot prompt. The image +may also be built with default boot parameters so users can normally just +boot directly to the live system without specifying any options when all of +the defaults are suitable. In particular, the argument to #{lb +--bootappend-live}# consists of any default kernel command line options for +the Live system, such as persistence, keyboard layouts, or timezone. See +{Customizing locale and language}#customizing-locale-and-language, for +example. + +Build-time configuration options are described in the #{lb config}# man +page. Boot-time options are described in the man pages for live-boot and +live-config. Although the live-boot and live-config packages are installed +within the live system you are building, it is recommended that you also +install them on your build system for easy reference when you are working on +your configuration. It is safe to do so, as none of the scripts contained +within them are executed unless the system is configured as a live system. + +2~stages-of-the-build Stages of the build + +The build process is divided into stages, with various customizations +applied in sequence in each. The first stage to run is the *{bootstrap}* +stage. This is the initial phase of populating the chroot directory with +packages to make a barebones Debian system. This is followed by the +*{chroot}* stage, which completes the construction of chroot directory, +populating it with all of the packages listed in the configuration, along +with any other materials. Most customization of content occurs in this +stage. The final stage of preparing the live image is the *{binary}* stage, +which builds a bootable image, using the contents of the chroot directory to +construct the root filesystem for the Live system, and including the +installer and any other additional material on the target medium outside of +the Live system's filesystem. After the live image is built, if enabled, the +source tarball is built in the *{source}* stage. + +Within each of these stages, there is a particular sequence in which +commands are applied. These are arranged in such a way as to ensure +customizations can be layered in a reasonable fashion. For example, within +the *{chroot}* stage, preseeds are applied before any packages are +installed, packages are installed before any locally included files are +copied, and hooks are run later, after all of the materials are in place. + +2~ Supplement lb config with files + +Although #{lb config}# creates a skeletal configuration in the #{config/}# +directory, to accomplish your goals, you may need to provide additional +files in subdirectories of #{config/}#. Depending on where the files are +stored in the configuration, they may be copied into the live system's +filesystem or into the binary image filesystem, or may provide build-time +configurations of the system that would be cumbersome to pass as +command-line options. You may include things such as custom lists of +packages, custom artwork, or hook scripts to run either at build time or at +boot time, boosting the already considerable flexibility of debian-live with +code of your own. + +2~ Customization tasks + +The following chapters are organized by the kinds of customization task +users typically perform: {Customizing package +installation}#customizing-package-installation, {Customizing +contents}#customizing-contents and {Customizing locale and +language}#customizing-locale-and-language cover just a few of the things you +might want to do. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-packages.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-packages.ssi new file mode 100644 index 0000000..dd6bd88 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-packages.ssi @@ -0,0 +1,643 @@ +:B~ Customizing package installation + +1~customizing-package-installation Customizing package installation + +Perhaps the most basic customization of a live system is the selection of +packages to be included in the image. This chapter guides you through the +various build-time options to customize live-build's installation of +packages. The broadest choices influencing which packages are available to +install in the image are the distribution and archive areas. To ensure +decent download speeds, you should choose a nearby distribution mirror. You +can also add your own repositories for backports, experimental or custom +packages, or include packages directly as files. You can define lists of +packages, including metapackages which will install many related packages at +once, such as packages for a particular desktop or language. Finally, a +number of options give some control over /{apt}/, or if you prefer, +/{aptitude}/, at build time when packages are installed. You may find these +handy if you use a proxy, want to disable installation of recommended +packages to save space, or need to control which versions of packages are +installed via APT pinning, to name a few possibilities. + +2~ Package sources + +3~ Distribution, archive areas and mode + +The distribution you choose has the broadest impact on which packages are +available to include in your live image. Specify the codename, which +defaults to ${testing} for the ${testing} version of live-build. Any current +distribution carried in the archive may be specified by its codename +here. (See {Terms}#terms for more details.) The #{--distribution}# option +not only influences the source of packages within the archive, but also +instructs live-build to behave as needed to build each supported +distribution. For example, to build against the *{unstable}* release, sid, +specify: + +code{ + + $ lb config --distribution sid + +}code + +Within the distribution archive, archive areas are major divisions of the +archive. In Debian, these are #{main}#, #{contrib}# and #{non-free}#. Only +#{main}# contains software that is part of the Debian distribution, hence +that is the default. One or more values may be specified, e.g. + +code{ + + $ lb config --archive-areas "main contrib non-free" + +}code + +Experimental support is available for some Debian derivatives through a +#{--mode}# option. By default, this option is set to #{debian}# only if you +are building on a Debian or on an unknown system. If #{lb config}# is +invoked on any of the supported derivatives, it will default to create an +image of that derivative. If #{lb config}# is run in e.g. #{ubuntu}# mode, +the distribution names and archive areas for the specified derivative are +supported instead of the ones for Debian. The mode also modifies live-build +behaviour to suit the derivatives. + +*{Note:}* The projects for whom these modes were added are primarily responsible for supporting users of these options. The ${project}, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves. + +3~ Distribution mirrors + +The Debian archive is replicated across a large network of mirrors around +the world so that people in each region can choose a nearby mirror for best +download speed. Each of the #{--mirror-*}# options governs which +distribution mirror is used at various stages of the build. Recall from +{Stages of the build}#stages-of-the-build that the *{bootstrap}* stage is +when the chroot is initially populated by /{debootstrap}/ with a minimal +system, and the *{chroot}* stage is when the chroot used to construct the +live system's filesystem is built. Thus, the corresponding mirror switches +are used for those stages, and later, in the *{binary}* stage, the +#{--mirror-binary}# and #{--mirror-binary-security}# values are used, +superseding any mirrors used in an earlier stage. + +3~distribution-mirrors-build-time Distribution mirrors used at build time + +To set the distribution mirrors used at build time to point at a local +mirror, it is sufficient to set #{--mirror-bootstrap}# and +#{--mirror-chroot-security}# as follows. + +code{ + + $ lb config --mirror-bootstrap http://localhost/debian/ \ + --mirror-chroot-security http://localhost/debian-security/ + +}code + +The chroot mirror, specified by #{--mirror-chroot}#, defaults to the +#{--mirror-bootstrap}# value. + +3~ Distribution mirrors used at run time + +The #{--mirror-binary*}# options govern the distribution mirrors placed in +the binary image. These may be used to install additional packages while +running the live system. The defaults employ #{httpredir.debian.org}#, a +service that chooses a geographically close mirror based, among other +things, on the user's IP family and the availability of the mirrors. This is +a suitable choice when you cannot predict which mirror will be best for all +of your users. Or you may specify your own values as shown in the example +below. An image built from this configuration would only be suitable for +users on a network where "#{mirror}#" is reachable. + +code{ + + $ lb config --mirror-binary http://mirror/debian/ \ + --mirror-binary-security http://mirror/debian-security/ \ + --mirror-binary-backports http://mirror/debian-backports/ + +}code + +3~additional-repositories Additional repositories + +You may add more repositories, broadening your package choices beyond what +is available in your target distribution. These may be, for example, for +backports, experimental or custom packages. To configure additional +repositories, create #{config/archives/your-repository.list.chroot}#, and/or +#{config/archives/your-repository.list.binary}# files. As with the +#{--mirror-*}# options, these govern the repositories used in the *{chroot}* +stage when building the image, and in the *{binary}* stage, i.e. for use +when running the live system. + +For example, #{config/archives/live.list.chroot}# allows you to install +packages from the debian-live snapshot repository at live system build time. + +code{ + + deb http://live-systems.org/ sid-snapshots main contrib non-free + +}code + +If you add the same line to #{config/archives/live.list.binary}#, the +repository will be added to your live system's #{/etc/apt/sources.list.d/}# +directory. + +If such files exist, they will be picked up automatically. + +You should also put the GPG key used to sign the repository into +#{config/archives/your-repository.key.{binary,chroot}}# files. + +Should you need custom APT pinning, such APT preferences snippets can be +placed in #{config/archives/your-repository.pref.{binary,chroot}}# files and +will be automatically added to your live system's +#{/etc/apt/preferences.d/}# directory. + +2~choosing-packages-to-install Choosing packages to install + +There are a number of ways to choose which packages live-build will install +in your image, covering a variety of different needs. You can simply name +individual packages to install in a package list. You can also use +metapackages in those lists, or select them using package control file +fields. And finally, you may place package files in your #{config/}# tree, +which is well suited to testing of new or experimental packages before they +are available from a repository. + +3~package-lists Package lists + +Package lists are a powerful way of expressing which packages should be +installed. The list syntax supports conditional sections which makes it easy +to build lists and adapt them for use in multiple configurations. Package +names may also be injected into the list using shell helpers at build time. + +*{Note:}* The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See {Choosing apt or aptitude}#choosing-apt-or-aptitude for more details. + +3~using-metapackages Using metapackages + +The simplest way to populate your package list is to use a task metapackage +maintained by your distribution. For example: + +code{ + + $ lb config + $ echo task-gnome-desktop > config/package-lists/desktop.list.chroot + +}code + +This supercedes the older predefined list method supported in #{live-build}# +2.x. Unlike predefined lists, task metapackages are not specific to the Live +System project. Instead, they are maintained by specialist working groups +within the distribution and therefore reflect the consensus of each group +about which packages best serve the needs of the intended users. They also +cover a much broader range of use cases than the predefined lists they +replace. + +All task metapackages are prefixed #{task-}#, so a quick way to determine +which are available (though it may contain a handful of false hits that +match the name but aren't metapackages) is to match on the package name +with: + +code{ + + $ apt-cache search --names-only ^task- + +}code + +In addition to these, you will find other metapackages with various +purposes. Some are subsets of broader task packages, like #{gnome-core}#, +while others are individual specialized parts of a Debian Pure Blend, such +as the #{education-*}# metapackages. To list all metapackages in the +archive, install the #{debtags}# package and list all packages with the +#{role::metapackage}# tag as follows: + +code{ + + $ debtags search role::metapackage + +}code + +3~ Local package lists + +Whether you list metapackages, individual packages, or a combination of +both, all local package lists are stored in #{config/package-lists/}#. Since +more than one list can be used, this lends itself well to modular +designs. For example, you may decide to devote one list to a particular +choice of desktop, another to a collection of related packages that might as +easily be used on top of a different desktop. This allows you to experiment +with different combinations of sets of packages with a minimum of fuss, +sharing common lists between different live image projects. + +Package lists that exist in this directory need to have a #{.list}# suffix +in order to be processed, and then an additional stage suffix, #{.chroot}# +or #{.binary}# to indicate which stage the list is for. + +*{Note:}* If you don't specify the stage suffix, the list will be used for both stages. Normally, you want to specify #{.list.chroot}# so that the packages will only be installed in the live filesystem and not have an extra copy of the #{.deb}# placed on the medium. + +3~ Local binary package lists + +To make a binary stage list, place a file suffixed with #{.list.binary}# in +#{config/package-lists/}#. These packages are not installed in the live +filesystem, but are included on the live medium under #{pool/}#. You would +typically use such a list with one of the non-live installer variants. As +mentioned above, if you want this list to be the same as your chroot stage +list, simply use the #{.list}# suffix by itself. + +3~generated-package-lists Generated package lists + +It sometimes happens that the best way to compose a list is to generate it +with a script. Any line starting with an exclamation point indicates a +command to be executed within the chroot when the image is built. For +example, one might include the line #{! grep-aptavail -n -sPackage +-FPriority standard | sort}# in a package list to produce a sorted list of +available packages with #{Priority: standard}#. + +In fact, selecting packages with the #{grep-aptavail}# command (from the +#{dctrl-tools}# package) is so useful that #{live-build}# provides a +#{Packages}# helper script as a convenience. This script takes two +arguments: #{field}# and #{pattern}#. Thus, you can create a list with the +following contents: + +code{ + + $ lb config + $ echo '! Packages Priority standard' > config/package-lists/standard.list.chroot + +}code + +3~ Using conditionals inside package lists + +Any of the live-build configuration variables stored in #{config/*}# (minus +the #{LB_}# prefix) may be used in conditional statements in package +lists. Generally, this means any #{lb config}# option uppercased and with +dashes changed to underscores. But in practice, it is only the ones that +influence package selection that make sense, such as #{DISTRIBUTION}#, +#{ARCHITECTURES}# or #{ARCHIVE_AREAS}#. + +For example, to install #{ia32-libs}# if the #{--architectures amd64}# is +specified: + +code{ + + #if ARCHITECTURES amd64 + ia32-libs + #endif + +}code + +You may test for any one of a number of values, e.g. to install +/{memtest86+}/ if either #{--architectures i386}# or #{--architectures +amd64}# is specified: + +code{ + + #if ARCHITECTURES i386 amd64 + memtest86+ + #endif + +}code + +You may also test against variables that may contain more than one value, +e.g. to install /{vrms}/ if either #{contrib}# or #{non-free}# is specified +via #{--archive-areas}#: + +code{ + + #if ARCHIVE_AREAS contrib non-free + vrms + #endif + +}code + +The nesting of conditionals is not supported. + +% FIXME: + +3~ Removing packages at install time + +You can list packages in files with #{.list.chroot_live}# and +#{.list.chroot_install}# suffixes inside the #{config/package-lists}# +directory. If both a live and an install list exist, the packages in the +#{.list.chroot_live}# list are removed with a hook after the installation +(if the user uses the installer). The packages in the +#{.list.chroot_install}# list are present both in the live system and in the +installed system. This is a special tweak for the installer and may be +useful if you have #{--debian-installer live}# set in your config, and wish +to remove live system-specific packages at install time. + +3~desktop-and-language-tasks Desktop and language tasks + +Desktop and language tasks are special cases that need some extra planning +and configuration. Live images are different from Debian Installer images in +this respect. In the Debian Installer, if the medium was prepared for a +particular desktop environment flavour, the corresponding task will be +automatically installed. Thus, there are internal #{gnome-desktop}#, +#{kde-desktop}#, #{lxde-desktop}# and #{xfce-desktop}# tasks, none of which +are offered in #{tasksel}#'s menu. Likewise, there are no menu entries for +tasks for languages, but the user's language choice during the install +influences the selection of corresponding language tasks. + +When developing a desktop live image, the image typically boots directly to +a working desktop, the choices of both desktop and default language having +been made at build time, not at run time as in the case of the Debian +Installer. That's not to say that a live image couldn't be built to support +multiple desktops or multiple languages and offer the user a choice, but +that is not live-build's default behaviour. + +Because there is no provision made automatically for language tasks, which +include such things as language-specific fonts and input-method packages, if +you want them, you need to specify them in your configuration. For example, +a GNOME desktop image containing support for German might include these task +metapackages: + +code{ + + $ lb config + $ echo "task-gnome-desktop task-laptop" >> config/package-lists/my.list.chroot + $ echo "task-german task-german-desktop task-german-gnome-desktop" >> config/package-lists/my.list.chroot + +}code + +3~kernel-flavour-and-version Kernel flavour and version + +One or more kernel flavours will be included in your image by default, +depending on the architecture. You can choose different flavours via the +#{--linux-flavours}# option. Each flavour is suffixed to the default stub +#{linux-image}# to form each metapackage name which in turn depends on an +exact kernel package to be included in your image. + +Thus by default, an #{amd64}# architecture image will include the +#{linux-image-amd64}# flavour metapackage, and an #{i386}# architecture +image will include the #{linux-image-586}# metapackage. + +When more than one kernel package version is available in your configured +archives, you can specify a different kernel package name stub with the +#{--linux-packages}# option. For example, supposing you are building an +#{amd64}# architecture image and add the experimental archive for testing +purposes so you can install the #{linux-image-3.18.0-trunk-amd64}# +kernel. You would configure that image as follows: + +code{ + + $ lb config --linux-packages linux-image-3.18.0-trunk + $ echo "deb http://ftp.debian.org/debian/ experimental main" > config/archives/experimental.list.chroot + +}code + +3~custom-kernels Custom kernels + +You can build and include your own custom kernels, so long as they are +integrated within the Debian package management system. The live-build +system does not support kernels not built as #{.deb}# packages. + +The proper and recommended way to deploy your own kernel packages is to +follow the instructions in the #{kernel-handbook}#. Remember to modify the +ABI and flavour suffixes appropriately, then include a complete build of the +#{linux}# and matching #{linux-latest}# packages in your repository. + +If you opt to build the kernel packages without the matching metapackages, +you need to specify an appropriate #{--linux-packages}# stub as discussed in +{Kernel flavour and version}#kernel-flavour-and-version. As we explain in +{Installing modified or third-party +packages}#installing-modified-or-third-party-packages, it is best if you +include your custom kernel packages in your own repository, though the +alternatives discussed in that section work as well. + +It is beyond the scope of this document to give advice on how to customize +your kernel. However, you must at least ensure your configuration satisfies +these minimum requirements: + +_* Use an initial ramdisk. + +_* Include the union filesystem module (i.e. usually #{aufs}#). + +_* Include any other filesystem modules required by your configuration +(i.e. usually #{squashfs}#). + +2~installing-modified-or-third-party-packages Installing modified or +third-party packages + +While it is against the philosophy of a live system, it may sometimes be +necessary to build a live system with modified versions of packages that are +in the Debian repository. This may be to modify or support additional +features, languages and branding, or even to remove elements of existing +packages that are undesirable. Similarly, "third-party" packages may be used +to add bespoke and/or proprietary functionality. + +This section does not cover advice regarding building or maintaining +modified packages. Joachim Breitner's 'How to fork privately' method from +http://www.joachim-breitner.de/blog/archives/282-How-to-fork-privately.html +may be of interest, however. The creation of bespoke packages is covered in +the Debian New Maintainers' Guide at https://www.debian.org/doc/maint-guide/ +and elsewhere. + +There are two ways of installing modified custom packages: + +_* #{packages.chroot}# + +_* Using a custom APT repository + +Using #{packages.chroot}# is simpler to achieve and useful for "one-off" +customizations but has a number of drawbacks, while using a custom APT +repository is more time-consuming to set up. + +3~ Using #{packages.chroot}# to install custom packages + +To install a custom package, simply copy it to the +#{config/packages.chroot/}# directory. Packages that are inside this +directory will be automatically installed into the live system during build +- you do not need to specify them elsewhere. + +Packages *{must}* be named in the prescribed way. One simple way to do this +is to use #{dpkg-name}#. + +Using #{packages.chroot}# for installation of custom packages has +disadvantages: + +_* It is not possible to use secure APT. + +_* You must install all appropriate packages in the +#{config/packages.chroot/}# directory. + +_* It does not lend itself to storing live system configurations in revision +control. + +3~ Using an APT repository to install custom packages + +Unlike using #{packages.chroot}#, when using a custom APT repository you +must ensure that you specify the packages elsewhere. See {Choosing packages +to install}#choosing-packages-to-install for details. + +While it may seem unnecessary effort to create an APT repository to install +custom packages, the infrastructure can be easily re-used at a later date to +offer updates of the modified packages. + +3~ Custom packages and APT + +live-build uses APT to install all packages into the live system so will +therefore inherit behaviours from this program. One relevant example is that +(assuming a default configuration) given a package available in two +different repositories with different version numbers, APT will elect to +install the package with the higher version number. + +Because of this, you may wish to increment the version number in your custom +packages' #{debian/changelog}# files to ensure that your modified version is +installed over one in the official Debian repositories. This may also be +achieved by altering the live system's APT pinning preferences - see {APT +pinning}#apt-pinning for more information. + +2~ Configuring APT at build time + +You can configure APT through a number of options applied only at build +time. (APT configuration used in the running live system may be configured +in the normal way for live system contents, that is, by including the +appropriate configurations through #{config/includes.chroot/}#.) For a +complete list, look for options starting with #{apt}# in the #{lb_config}# +man page. + +3~choosing-apt-or-aptitude Choosing apt or aptitude + +You can elect to use either /{apt}/ or /{aptitude}/ when installing packages +at build time. Which utility is used is governed by the #{--apt}# argument +to #{lb config}#. Choose the method implementing the preferred behaviour for +package installation, the notable difference being how missing packages are +handled. + +_* #{apt}#: With this method, if a missing package is specified, the package +installation will fail. This is the default setting. + +_* #{aptitude}#: With this method, if a missing package is specified, the +package installation will succeed. + +3~ Using a proxy with APT + +One commonly required APT configuration is to deal with building an image +behind a proxy. You may specify your APT proxy with the #{--apt-ftp-proxy}# +or #{--apt-http-proxy}# options as needed, e.g. + +code{ + + $ lb config --apt-http-proxy http://proxy/ + +}code + +3~tweaking-apt-to-save-space Tweaking APT to save space + +You may find yourself needing to save some space on the image medium, in +which case one or the other or both of the following options may be of +interest. + +If you don't want to include APT indices in the image, you can omit those +with: + +code{ + + $ lb config --apt-indices false + +}code + +This will not influence the entries in #{/etc/apt/sources.list}#, but merely +whether #{/var/lib/apt}# contains the indices files or not. The tradeoff is +that APT needs those indices in order to operate in the live system, so +before performing #{apt-cache search}# or #{apt-get install}#, for instance, +the user must #{apt-get update}# first to create those indices. + +If you find the installation of recommended packages bloats your image too +much, provided you are prepared to deal with the consequences discussed +below, you may disable that default option of APT with: + +code{ + + $ lb config --apt-recommends false + +}code + +The most important consequence of turning off recommends is that +#{live-boot}# and #{live-config}# themselves recommend some packages that +provide important functionality used by most Live configurations, such as +#{user-setup}# which #{live-config}# recommends and is used to create the +live user. In all but the most exceptional circumstances you need to add +back at least some of these recommends to your package lists or else your +image will not work as expected, if at all. Look at the recommended packages +for each of the #{live-*}# packages included in your build and if you are +not certain you can omit them, add them back into your package lists. + +The more general consequence is that if you don't install recommended +packages for any given package, that is, "packages that would be found +together with this one in all but unusual installations" (Debian Policy +Manual, section 7.2), some packages that users of your Live system actually +need may be omitted. Therefore, we suggest you review the difference turning +off recommends makes to your packages list (see the #{binary.packages}# file +generated by #{lb build}#) and re-include in your list any missing packages +that you still want installed. Alternatively, if you find you only want a +small number of recommended packages left out, leave recommends enabled and +set a negative APT pin priority on selected packages to prevent them from +being installed, as explained in {APT pinning}#apt-pinning. + +3~ Passing options to apt or aptitude + +If there is not a #{lb config}# option to alter APT's behaviour in the way +you need, use #{--apt-options}# or #{--aptitude-options}# to pass any +options through to your configured APT tool. See the man pages for #{apt}# +and #{aptitude}# for details. Note that both options have default values +that you will need to retain in addition to any overrides you may +provide. So, for example, suppose you have included something from +#{snapshot.debian.org}# for testing purposes and want to specify +#{Acquire::Check-Valid-Until=false}# to make APT happy with the stale +#{Release}# file, you would do so as per the following example, appending +the new option after the default value #{--yes}#: + +code{ + + $ lb config --apt-options "--yes -oAcquire::Check-Valid-Until=false" + +}code + +Please check the man pages to fully understand these options and when to use +them. This is an example only and should not be construed as advice to +configure your image this way. This option would not be appropriate for, +say, a final release of a live image. + +For more complicated APT configurations involving #{apt.conf}# options you +might want to create a #{config/apt/apt.conf}# file instead. See also the +other #{apt-*}# options for a few convenient shortcuts for frequently needed +options. + +3~apt-pinning APT pinning + +For background, please first read the #{apt_preferences(5)}# man page. APT +pinning can be configured either for build time, or else for run time. For +the former, create #{config/archives/*.pref}#, +#{config/archives/*.pref.chroot}#, and #{config/apt/preferences}#. For the +latter, create #{config/includes.chroot/etc/apt/preferences}#. + +Let's say you are building a ${testing} live system but need all the live +packages that end up in the binary image to be installed from sid at build +time. You need to add sid to your APT sources and pin the live packages from +it higher, but all other packages from it lower, than the default +priority. Thus, only the packages you want are installed from sid at build +time and all others are taken from the target system distribution, +${testing}. The following will accomplish this: + +code{ + + $ echo "deb http://mirror/debian/ sid main" > config/archives/sid.list.chroot + $ cat >> config/archives/sid.pref.chroot << EOF + Package: live-* + Pin: release n=sid + Pin-Priority: 600 + + Package: * + Pin: release n=sid + Pin-Priority: 1 + EOF + +}code + +Negative pin priorities will prevent a package from being installed, as in +the case where you do not want a package that is recommended by another +package. Suppose you are building an LXDE image using #{task-lxde-desktop}# +in #{config/package-lists/desktop.list.chroot}#, but don't want the user +prompted to store wifi passwords in the keyring. This metapackage depends on +/{lxde-core}/, which recommends /{gksu}/, which in turn recommends +/{gnome-keyring}/. So you want to omit the recommended /{gnome-keyring}/ +package. This can be done by adding the following stanza to +#{config/apt/preferences}#: + +code{ + + Package: gnome-keyring + Pin: version * + Pin-Priority: -1 + +}code diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-runtime.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-runtime.ssi new file mode 100644 index 0000000..3e44cb3 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_customization-runtime.ssi @@ -0,0 +1,441 @@ +:B~ Customizing run time behaviours + +1~customizing-run-time-behaviours Customizing run time behaviours + +All configuration that is done during run time is done by live-config. Here +are some of the most common options of live-config that users are interested +in. A full list of all possibilities can be found in the man page of +live-config. + +2~ Customizing the live user + +One important consideration is that the live user is created by live-boot at +boot time, not by live-build at build time. This not only influences where +materials relating to the live user are introduced in your build, as +discussed in {Live/chroot local includes}#live-chroot-local-includes, but +also any groups and permissions associated with the live user. + +You can specify additional groups that the live user will belong to by using +any of the possibilities to configure live-config. For example, to add the +live user to the #{fuse}# group, you can either add the following file in +#{config/includes.chroot/etc/live/config/user-setup.conf}#: + +code{ + + LIVE_USER_DEFAULT_GROUPS="audio cdrom dip floppy video plugdev netdev powerdev scanner bluetooth fuse" + +}code + +or use +#{live-config.user-default-groups=audio,cdrom,dip,floppy,video,plugdev,netdev,powerdev,scanner,bluetooth,fuse}# +as a boot parameter. + +It is also possible to change the default username "user" and the default +password "live". If you want to do that for any reason, you can easily +achieve it as follows: + +To change the default username you can simply specify it in your config: + +code{ + + $ lb config --bootappend-live "boot=live components username=live-user" + +}code + +One possible way of changing the default password is by means of a hook as +described in {Boot-time hooks}#boot-time-hooks. In order to do that you can +use the "passwd" hook from #{/usr/share/doc/live-config/examples/hooks}#, +prefix it accordingly (e.g. 2000-passwd) and add it to +#{config/includes.chroot/lib/live/config/}# + +2~customizing-locale-and-language Customizing locale and language + +When the live system boots, language is involved in two steps: + +_* the locale generation + +_* setting the keyboard configuration + +The default locale when building a Live system is +#{locales=en_US.UTF-8}#. To define the locale that should be generated, use +the #{locales}# parameter in the #{--bootappend-live}# option of #{lb +config}#, e.g. + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8" + +}code + +Multiple locales may be specified as a comma-delimited list. + +This parameter, as well as the keyboard configuration parameters indicated +below, can also be used at the kernel command line. You can specify a locale +by #{language_country}# (in which case the default encoding is used) or the +full #{language_country.encoding}# word. A list of supported locales and the +encoding for each can be found in #{/usr/share/i18n/SUPPORTED}#. + +Both the console and X keyboard configuration are performed by +#{live-config}# using the #{console-setup}# package. To configure them, use +the #{keyboard-layouts}#, #{keyboard-variants}#, #{keyboard-options}# and +#{keyboard-model}# boot parameters via the #{--bootappend-live}# +option. Valid options for these can be found in +#{/usr/share/X11/xkb/rules/base.lst}#. To find layouts and variants for a +given language, try searching for the English name of the language and/or +the country where the language is spoken, e.g: + +code{ + +$ egrep -i '(^!|german.*switzerland)' /usr/share/X11/xkb/rules/base.lst + ! model + ! layout + ch German (Switzerland) + ! variant + legacy ch: German (Switzerland, legacy) + de_nodeadkeys ch: German (Switzerland, eliminate dead keys) + de_sundeadkeys ch: German (Switzerland, Sun dead keys) + de_mac ch: German (Switzerland, Macintosh) + ! option + +}code + +Note that each variant lists the layout to which it applies in the +description. + +Often, only the layout needs to be configured. For example, to get the +locale files for German and Swiss German keyboard layout in X use: + +code{ + + $ lb config --bootappend-live "boot=live components locales=de_CH.UTF-8 keyboard-layouts=ch" + +}code + +However, for very specific use cases, you may wish to include other +parameters. For example, to set up a French system with a French-Dvorak +layout (called Bepo) on a TypeMatrix EZ-Reach 2030 USB keyboard, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variants=bepo keyboard-model=tm2030usb" + +}code + +Multiple values may be specified as comma-delimited lists for each of the +#{keyboard-*}# options, with the exception of #{keyboard-model}#, which +accepts only one value. Please see the #{keyboard(5)}# man page for details +and examples of #{XKBMODEL}#, #{XKBLAYOUT}#, #{XKBVARIANT}# and +#{XKBOPTIONS}# variables. If multiple #{keyboard-variants}# values are +given, they will be matched one-to-one with #{keyboard-layouts}# values (see +#{setxkbmap(1)}# #{-variant}# option). Empty values are allowed; e.g. to +define two layouts, the default being US QWERTY and the other being US +Dvorak, use: + +code{ + + $ lb config --bootappend-live \ + "boot=live components keyboard-layouts=us,us keyboard-variants=,dvorak" + +}code + +2~persistence Persistence + +A live cd paradigm is a pre-installed system which runs from read-only +media, like a cdrom, where writes and modifications do not survive reboots +of the host hardware which runs it. + +A live system is a generalization of this paradigm and thus supports other +media in addition to CDs; but still, in its default behaviour, it should be +considered read-only and all the run-time evolutions of the system are lost +at shutdown. + +'Persistence' is a common name for different kinds of solutions for saving +across reboots some, or all, of this run-time evolution of the system. To +understand how it works it would be handy to know that even if the system is +booted and run from read-only media, modifications to the files and +directories are written on writable media, typically a ram disk (tmpfs) and +ram disks' data do not survive reboots. + +The data stored on this ramdisk should be saved on a writable persistent +medium like local storage media, a network share or even a session of a +multisession (re)writable CD/DVD. All these media are supported in live +systems in different ways, and all but the last one require a special boot +parameter to be specified at boot time: #{persistence}#. + +If the boot parameter #{persistence}# is set (and #{nopersistence}# is not +set), local storage media (e.g. hard disks, USB drives) will be probed for +persistence volumes during boot. It is possible to restrict which types of +persistence volumes to use by specifying certain boot parameters described +in the live-boot(7) man page. A persistence volume is any of the following: + +_* a partition, identified by its GPT name. + +_* a filesystem, identified by its filesystem label. + +_* an image file located on the root of any readable filesystem (even an +NTFS partition of a foreign OS), identified by its filename. + +The volume label for overlays must be #{persistence}# but it will be ignored +unless it contains in its root a file named #{persistence.conf}# which is +used to fully customize the volume's persistence, this is to say, specifying +the directories that you want to save in your persistence volume after a +reboot. See {The persistence.conf file}#persistence-conf for more details. + +Here are some examples of how to prepare a volume to be used for +persistence. It can be, for instance, an ext4 partition on a hard disk or on +a usb key created with, e.g.: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + +}code + +See also {Using the space left on a USB stick}#using-usb-extra-space. + +If you already have a partition on your device, you could just change the +label with one of the following: + +code{ + + # tune2fs -L persistence /dev/sdb1 # for ext2,3,4 filesystems + +}code + +Here's an example of how to create an ext4-based image file to be used for +persistence: + +code{ + + $ dd if=/dev/null of=persistence bs=1 count=0 seek=1G # for a 1GB sized image file + $ /sbin/mkfs.ext4 -F persistence + +}code + +Once the image file is created, as an example, to make #{/usr}# persistent +but only saving the changes you make to that directory and not all the +contents of #{/usr}#, you can use the "union" option. If the image file is +located in your home directory, copy it to the root of your hard drive's +filesystem and mount it in #{/mnt}# as follows: + +code{ + + # cp persistence / + # mount -t ext4 /persistence /mnt + +}code + +Then, create the #{persistence.conf}# file adding content and unmount the +image file. + +code{ + + # echo "/usr union" >> /mnt/persistence.conf + # umount /mnt + +}code + +Now, reboot into your live medium with the boot parameter "persistence". + +3~persistence-conf The persistence.conf file + +A volume with the label #{persistence}# must be configured by means of the +#{persistence.conf}# file to make arbitrary directories persistent. That +file, located on the volume's filesystem root, controls which directories it +makes persistent, and in which way. + +How custom overlay mounts are configured is described in full detail in the +persistence.conf(5) man page, but a simple example should be sufficient for +most uses. Let's say we want to make our home directory and APT cache +persistent in an ext4 filesystem on the /dev/sdb1 partition: + +code{ + + # mkfs.ext4 -L persistence /dev/sdb1 + # mount -t ext4 /dev/sdb1 /mnt + # echo "/home" >> /mnt/persistence.conf + # echo "/var/cache/apt" >> /mnt/persistence.conf + # umount /mnt + +}code + +Then we reboot. During the first boot the contents of #{/home}# and +#{/var/cache/apt}# will be copied into the persistence volume, and from then +on all changes to these directories will live in the persistence +volume. Please note that any paths listed in the #{persistence.conf}# file +cannot contain white spaces or the special #{.}# and #{..}# path +components. Also, neither #{/lib}#, #{/lib/live}# (or any of their +sub-directories) nor #{/}# can be made persistent using custom mounts. As a +workaround for this limitation you can add #{/ union}# to your +#{persistence.conf}# file to achieve full persistence. + +3~ Using more than one persistence store + +There are different methods of using multiple persistence store for +different use cases. For instance, using several volumes at the same time or +selecting only one, among various, for very specific purposes. + +Several different custom overlay volumes (with their own +#{persistence.conf}# files) can be used at the same time, but if several +volumes make the same directory persistent, only one of them will be +used. If any two mounts are "nested" (i.e. one is a sub-directory of the +other) the parent will be mounted before the child so no mount will be +hidden by the other. Nested custom mounts are problematic if they are listed +in the same #{persistence.conf}# file. See the persistence.conf(5) man page +for how to handle that case if you really need it (hint: you usually don't). + +One possible use case: If you wish to store the user data i.e. #{/home}# and +the superuser data i.e. #{/root}# in different partitions, create two +partitions with the #{persistence}# label and add a #{persistence.conf}# +file in each one like this, #{# echo "/home" > persistence.conf}# for the +first partition that will save the user's files and #{# echo "/root" > +persistence.conf}# for the second partition which will store the superuser's +files. Finally, use the #{persistence}# boot parameter. + +If a user would need multiple persistence store of the same type for +different locations or testing, such as #{private}# and #{work}#, the boot +parameter #{persistence-label}# used in conjunction with the boot parameter +#{persistence}# will allow for multiple but unique persistence media. An +example would be if a user wanted to use a persistence partition labeled +#{private}# for personal data like browser bookmarks or other types, they +would use the boot parameters: #{persistence}# +#{persistence-label=private}#. And to store work related data, like +documents, research projects or other types, they would use the boot +parameters: #{persistence}# #{persistence-label=work}#. + +It is important to remember that each of these volumes, #{private}# and +#{work}#, also needs a #{persistence.conf}# file in its root. The live-boot +man page contains more information about how to use these labels with legacy +names. + +3~ Using persistence with encryption + +Using the persistence feature means that some sensible data might get +exposed to risk. Especially if the persistent data is stored on a portable +device such as a usb stick or an external hard drive. That is when +encryption comes in handy. Even if the entire procedure might seem +complicated because of the number of steps to be taken, it is really easy to +handle encrypted partitions with live-boot. In order to use *{luks}*, which +is the supported encryption type, you need to install /{cryptsetup}/ both on +the machine you are creating the encrypted partition with and also in the +live system you are going to use the encrypted persistent partition with. + +To install /{cryptsetup}/ on your machine: + +code{ + + # apt-get install cryptsetup + +}code + +To install /{cryptsetup}/ in your live system, add it to your package-lists: + +code{ + + $ lb config + $ echo "cryptsetup" > config/package-lists/encryption.list.chroot + +}code + +Once you have your live system with /{cryptsetup}/, you basically only need +to create a new partition, encrypt it and boot with the #{persistence}# and +#{persistence-encryption=luks}# parameters. We could have already +anticipated this step and added the boot parameters following the usual +procedure: + +code{ + + $ lb config --bootappend-live "boot=live components persistence persistence-encryption=luks" + +}code + +Let's go into the details for all of those who are not familiar with +encryption. In the following example we are going to use a partition on a +usb stick which corresponds to #{/dev/sdc2}#. Please be warned that you need +to determine which partition is the one you are going to use in your +specific case. + +The first step is plugging in your usb stick and determine which device it +is. The recommended method of listing devices in live-manual is using #{ls +-l /dev/disk/by-id}#. After that, create a new partition and then, encrypt +it with a passphrase as follows: + +code{ + + # cryptsetup --verify-passphrase luksFormat /dev/sdc2 + +}code + +Then open the luks partition in the virtual device mapper. Use any name you +like. We use *{live}* here as an example: + +code{ + + # cryptsetup luksOpen /dev/sdc2 live + +}code + +The next step is filling the device with zeros before creating the +filesystem: + +code{ + + # dd if=/dev/zero of=/dev/mapper/live + +}code + +Now, we are ready to create the filesystem. Notice that we are adding the +label #{persistence}# so that the device is mounted as persistence store at +boot time. + +code{ + + # mkfs.ext4 -L persistence /dev/mapper/live + +}code + +To continue with our setup, we need to mount the device, for example in +#{/mnt}#. + +code{ + + # mount /dev/mapper/live /mnt + +}code + +And create the #{persistence.conf}# file in the root of the partition. This +is, as explained before, strictly necessary. See {The persistence.conf +file}#persistence-conf. + +code{ + + # echo "/ union" > /mnt/persistence.conf + +}code + +Then unmount the mount point: + +code{ + + # umount /mnt + +}code + +And optionally, although it might be a good way of securing the data we have +just added to the partition, we can close the device: + +code{ + + # cryptsetup luksClose live + +}code + +Let's summarize the process. So far, we have created an encryption capable +live system, which can be copied to a usb stick as explained in {Copying an +ISO hybrid image to a USB stick}#copying-iso-hybrid-to-usb. We have also +created an encrypted partition, which can be located in the same usb stick +to carry it around and we have configured the encrypted partition to be used +as persistence store. So now, we only need to boot the live system. At boot +time, live-boot will prompt us for the passphrase and will mount the +encrypted partition to be used for persistence. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_installation.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_installation.ssi new file mode 100644 index 0000000..3841f4c --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_installation.ssi @@ -0,0 +1,173 @@ +:B~ Installation + +1~installation Installation + +2~requirements Requirements + +Building live system images has very few system requirements: + +_* Superuser (root) access + +_* An up-to-date version of live-build + +_* A POSIX-compliant shell, such as /{bash}/ or /{dash}/ + +_* /{debootstrap}/ + +_* Linux 2.6 or newer. + +Note that using Debian or a Debian-derived distribution is not required - +live-build will run on almost any distribution with the above requirements. + +2~installing-live-build Installing live-build + +You can install live-build in a number of different ways: + +_* From the Debian repository + +_* From source + +_* From snapshots + +If you are using Debian, the recommended way is to install live-build via +the Debian repository. + +3~ From the Debian repository + +Simply install live-build like any other package: + +code{ + + # apt-get install live-build + +}code + +3~ From source + +live-build is developed using the Git version control system. On Debian +based systems, this is provided by the /{git}/ package. To check out the +latest code, execute: + +code{ + + $ git clone git://live-systems.org/git/live-build.git + +}code + +You can build and install your own Debian package by executing: + +code{ + + $ cd live-build + $ dpkg-buildpackage -b -uc -us + $ cd .. + +}code + +Now install whichever of the freshly built #{.deb}# files you were +interested in, e.g. + +code{ + + # dpkg -i live-build_4.0-1_all.deb + +}code + +You can also install live-build directly to your system by executing: + +code{ + + # make install + +}code + +and uninstall it with: + +code{ + + # make uninstall + +}code + +3~ From 'snapshots' + +If you do not wish to build or install live-build from source, you can use +snapshots. These are built automatically from the latest version in Git and +are available on http://live-systems.org/debian/. + +2~ Installing live-boot and live-config + +*{Note:}* You do not need to install live-boot or live-config on your system to create customized live systems. However, doing so will do no harm and is useful for reference purposes. If you only want the documentation, you may now install the /{live-boot-doc}/ and /{live-config-doc}/ packages separately. + +3~ From the Debian repository + +Both live-boot and live-config are available from the Debian repository as +per {Installing live-build}#installing-live-build. + +3~ From source + +To use the latest source from git, you can follow the process below. Please +ensure you are familiar with the terms mentioned in {Terms}#terms. + +_* Checkout the live-boot and live-config sources + +code{ + + $ git clone git://live-systems.org/git/live-boot.git + $ git clone git://live-systems.org/git/live-config.git + +}code + +Consult the live-boot and live-config man pages for details on customizing +if that is your reason for building these packages from source. + +_* Build live-boot and live-config .deb files + +You must build either on your target distribution or in a chroot containing +your target platform: this means if your target is ${testing} then you +should build against ${testing}. + +Use a personal builder such as /{pbuilder}/ or /{sbuild}/ if you need to +build live-boot for a target distribution that differs from your build +system. For example, for ${testing} live images, build live-boot in a +${testing} chroot. If your target distribution happens to match your build +system distribution, you may build directly on the build system using +#{dpkg-buildpackage}# (provided by the /{dpkg-dev}/ package): + +code{ + + $ cd live-boot + $ dpkg-buildpackage -b -uc -us + $ cd ../live-config + $ dpkg-buildpackage -b -uc -us + +}code + +_* Use applicable generated .deb files + +As live-boot and live-config are installed by live-build system, installing +the packages in the host system is not sufficient: you should treat the +generated .deb files like any other custom packages. Since your purpose for +building from source is likely to test new things over the short term before +the official release, follow {Installing modified or third-party +packages}#installing-modified-or-third-party-packages to temporarily include +the relevant files in your configuration. In particular, notice that both +packages are divided into a generic part, a documentation part and one or +more back-ends. Include the generic part, only one back-end matching your +configuration, and optionally the documentation. Assuming you are building a +live image in the current directory and have generated all .deb files for a +single version of both packages in the directory above, these bash commands +would copy all of the relevant packages including default back-ends: + +code{ + + $ cp ../live-boot{_,-initramfs-tools,-doc}*.deb config/packages.chroot/ + $ cp ../live-config{_,-sysvinit,-doc}*.deb config/packages.chroot/ + +}code + +3~ From 'snapshots' + +You can let live-build automatically use the latest snapshots of live-boot +and live-config by configuring the package repository on live-systems.org as +a third-party repository in your live-build configuration directory. diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_managing_a_configuration.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_managing_a_configuration.ssi new file mode 100644 index 0000000..6d54371 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_managing_a_configuration.ssi @@ -0,0 +1,133 @@ +:B~ Managing a configuration + +1~managing-a-configuration Managing a configuration + +This chapter explains how to manage a live configuration from initial +creation, through successive revisions and successive releases of both the +live-build software and the live image itself. + +2~ Dealing with configuration changes + +Live configurations rarely are perfect on the first try. It may be fine to +pass #{lb config}# options from the command-line to perform a single build, +but it is more typical to revise those options and build again until you are +satisfied. To support these changes, you will need auto scripts which ensure +your configuration is kept in a consistent state. + +3~ Why use auto scripts? What do they do? + +The #{lb config}# command stores the options you pass to it in #{config/*}# +files along with many other options set to default values. If you run #{lb +config}# again, it will not reset any option that was defaulted based on +your initial options. So, for example, if you run #{lb config}# again with a +new value for #{--binary-images}#, any dependent options that were defaulted +for the old image type may no longer work with the new ones. Nor are these +files intended to be read or edited. They store values for over a hundred +options, so nobody, let alone yourself, will be able to see in these which +options you actually specified. And finally, if you run #{lb config}#, then +upgrade live-build and it happens to rename an option, #{config/*}# would +still contain variables named after the old option that are no longer valid. + +For all these reasons, #{auto/*}# scripts will make your life easier. They +are simple wrappers to the #{lb config}#, #{lb build}# and #{lb clean}# +commands that are designed to help you manage your configuration. The +#{auto/config}# script stores your #{lb config}# command with all desired +options, the #{auto/clean}# script removes the files containing +configuration variable values, and the #{auto/build}# script keeps a +#{build.log}# of each build. Each of these scripts is run automatically +every time you run the corresponding #{lb}# command. By using these scripts, +your configuration is easier to read and is kept internally consistent from +one revision to the next. Also, it will be much easier for you identify and +fix options which need to change when you upgrade live-build after reading +the updated documentation. + +3~ Use example auto scripts + +For your convenience, live-build comes with example auto shell scripts to +copy and edit. Start a new, default configuration, then copy the examples +into it: + +code{ + + $ mkdir mylive && cd mylive && lb config + $ mkdir auto + $ cp /usr/share/doc/live-build/examples/auto/* auto/ + +}code + +Edit #{auto/config}#, adding any options as you see fit. For instance: + +code{ + + #!/bin/sh + lb config noauto \ + --architectures i386 \ + --linux-flavours 686-pae \ + --binary-images hdd \ + --mirror-bootstrap http://ftp.ch.debian.org/debian/ \ + --mirror-binary http://ftp.ch.debian.org/debian/ \ + "${@}" + +}code + +Now, each time you use #{lb config}#, #{auto/config}# will reset the +configuration based on these options. When you want to make changes to them, +edit the options in this file instead of passing them to #{lb config}#. When +you use #{lb clean}#, #{auto/clean}# will clean up the #{config/*}# files +along with any other build products. And finally, when you use #{lb build}#, +a log of the build will be written by #{auto/build}# in #{build.log}#. + +*{Note:}* A special #{noauto}# parameter is used here to suppress another call to #{auto/config}#, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the #{lb config}# command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next. + +2~clone-configuration-via-git Clone a configuration published via Git + +Use the #{lb config --config}# option to clone a Git repository that +contains a live system configuration. If you would like to base your +configuration on one maintained by the ${project}, look at +http://live-systems.org/gitweb/ for the repository named #{live-images}# in +the category #{Packages}#. This repository contains the configurations for +the live systems {prebuilt images}#downloading-prebuilt-images. + +For example, to build a standard image, use the #{live-images}# repository +as follows: + +code{ + + $ mkdir live-images && cd live-images + $ lb config --config git://live-systems.org/git/live-images.git + $ cd images/standard + +}code + +Edit #{auto/config}# and any other things you need in the #{config}# tree to +suit your needs. For example, the unofficial non-free prebuilt images are +made by simply adding #{--archive-areas "main contrib non-free"}#. + +You may optionally define a shortcut in your Git configuration by adding the +following to your #{${HOME}/.gitconfig}#: + +code{ + + [url "git://live-systems.org/git/"] + insteadOf = lso: + +}code + +This enables you to use #{lso:}# anywhere you need to specify the address of +a #{live-systems.org}# git repository. If you also drop the optional +#{.git}# suffix, starting a new image using this configuration is as easy +as: + +code{ + + $ lb config --config lso:live-images + +}code + +Cloning the entire #{live-images}# repository pulls the configurations used +for several images. If you feel like building a different image after you +have finished with the first one, change to another directory and again and +optionally, make any changes to suit your needs. + +In any case, remember that every time you will have to build the image as +superuser: #{lb build}# diff --git a/markup/pod-samples/pod/live-manual/media/text/ro/user_overview.ssi b/markup/pod-samples/pod/live-manual/media/text/ro/user_overview.ssi new file mode 100644 index 0000000..073a266 --- /dev/null +++ b/markup/pod-samples/pod/live-manual/media/text/ro/user_overview.ssi @@ -0,0 +1,130 @@ +:B~ Overview of tools + +1~overview-of-tools Overview of tools + +This chapter contains an overview of the three main tools used in building +live systems: live-build, live-boot and live-config. + +2~live-build The live-build package + +live-build is a collection of scripts to build live systems. These scripts +are also referred to as "commands". + +The idea behind live-build is to be a framework that uses a configuration +directory to completely automate and customize all aspects of building a +Live image. + +Many concepts are similar to those used to build Debian packages with +/{debhelper}/: + +_* The scripts have a central location for configuring their operation. In +/{debhelper}/, this is the #{debian/}# subdirectory of a package tree. For +example, dh_install will look, among others, for a file called +#{debian/install}# to determine which files should exist in a particular +binary package. In much the same way, live-build stores its configuration +entirely under a #{config/}# subdirectory. + +_* The scripts are independent - that is to say, it is always safe to run +each command. + +Unlike /{debhelper}/, live-build provides the tools to generate a skeleton +configuration directory. This could be considered to be similar to tools +such as /{dh-make}/. For more information about these tools, read on, since +the remainder of this section discuses the four most important +commands. Note that the preceding #{lb}# is a generic wrapper for live-build +commands. + +_* *{lb config}*: Responsible for initializing a Live system configuration +directory. See {The lb config command}#lb-config for more information. + +_* *{lb build}*: Responsible for starting a Live system build. See {The lb +build command}#lb-build for more information. + +_* *{lb clean}*: Responsible for removing parts of a Live system build. See +{The lb clean command}#lb-clean for more information. + +3~lb-config The #{lb config}# command + +As discussed in {live-build}#live-build, the scripts that make up live-build +read their configuration with the #{source}# command from a single directory +named #{config/}#. As constructing this directory by hand would be +time-consuming and error-prone, the #{lb config}# command can be used to +create the initial skeleton configuration tree. + +Issuing #{lb config}# without any arguments creates the #{config/}# +subdirectory which is populated with some default settings in configuration +files, and two skeleton trees named #{auto/}# and #{local/}#. + +code{ + + $ lb config + [2015-01-06 19:25:58] lb config + P: Creating config tree for a debian/stretch/i386 system + P: Symlinking hooks... + +}code + +Using #{lb config}# without any arguments would be suitable for users who +need a very basic image, or who intend to provide a more complete +configuration via #{auto/config}# later (see {Managing a +configuration}#managing-a-configuration for details). + +Normally, you will want to specify some options. For example, to specify +which package manager to use while building the image: + +code{ + + $ lb config --apt aptitude + +}code + +It is possible to specify many options, such as: + +code{ + + $ lb config --binary-images netboot --bootappend-live "boot=live components hostname=live-host username=live-user" ... + +}code + +A full list of options is available in the #{lb_config}# man page. + +3~lb-build The #{lb build}# command + +The #{lb build}# command reads in your configuration from the #{config/}# +directory. It then runs the lower level commands needed to build your Live +system. + +3~lb-clean The #{lb clean}# command + +It is the job of the #{lb clean}# command to remove various parts of a build +so subsequent builds can start from a clean state. By default, #{chroot}#, +#{binary}# and #{source}# stages are cleaned, but the cache is left +intact. Also, individual stages can be cleaned. For example, if you have +made changes that only affect the binary stage, use #{lb clean --binary}# +prior to building a new binary. If your changes invalidate the bootstrap +and/or package caches, e.g. changes to #{--mode}#, #{--architecture}#, or +#{--bootstrap}#, you must use #{lb clean --purge}#. See the #{lb_clean}# man +page for a full list of options. + +2~live-boot The live-boot package + +live-boot is a collection of scripts providing hooks for the +/{initramfs-tools}/, used to generate an initramfs capable of booting live +systems, such as those created by live-build. This includes the live system +ISOs, netboot tarballs, and USB stick images. + +At boot time it will look for read-only media containing a #{/live/}# +directory where a root filesystem (often a compressed filesystem image like +squashfs) is stored. If found, it will create a writable environment, using +aufs, for Debian like systems to boot from. + +More information on initial ramfs in Debian can be found in the Debian Linux +Kernel Handbook at http://kernel-handbook.alioth.debian.org/ in the chapter +on initramfs. + +2~live-config The live-config package + +live-config consists of the scripts that run at boot time after live-boot to +configure the live system automatically. It handles such tasks as setting +the hostname, locales and timezone, creating the live user, inhibiting cron +jobs and performing autologin of the live user. |