'''Thanks for your interest in contributing to the the Funtoo wiki!'''
= Introduction =
__NOTOC__
=== Types of Edits ===
LVM (Logical Volume Management) offers a great flexibility in managing your storage and significantly reduces server downtimes by allowing on-line disk space management: The great idea beneath LVM is to '''make the data and its storage loosely coupled''' through several layers of abstraction. You (the system administrator) have the hand of each of those layers making the entire space management process extremely simple and flexible through various set of coherent commands.
Before we get started, let's review what changes are okay to make, and what changes are not okay:
Several other well-known binary Linux distributions makes an aggressive use of LVM and several Unixes including HP-UX, AIX and Solaris offers since a while a similar functionality modulo the commands to be used. LVM is not mandatory but its usage can bring you additional flexibility and make your everyday life much more simpler.
{{TableStart}}
<tr class="active"><th>Type of Change</th><th>Okay?</th></tr>
<tr class="danger"><td>Adding work-arounds to problems experienced</td><td>No - open bug first on [http://bugs.funtoo.org bug tracker].</td></tr>
{{TableEnd}}
= Concepts =
{{important|Note that if you experience some problem with Funtoo Linux, during installation or otherwise, the proper course of action is to not add a work-around to our documentation, but to ''open a bug on our bug tracker.'' This is important because the problem you experienced may be a legitimate bug and the solution may be to fix the bug rather than add a work-around to our documentation. We may end up fixing a bug, making a documentation fix, or possibly both.}}
As usual, having a good idea of the concepts lying beneath is mandatory. LVM is not very complicated, but it is easy to become confused, especially because it is a multi-layered system; however LVM designers had the good idea of keeping the command names consistent between all LVM command sets, making your life easier.
=== Basics ===
LVM consists of, mainly, three things:
Here is a list of basic wiki information that you will need to know to get started:
* '''Physical volumes (or ''PV'')''': nothing more than a physical storage space. A physical volume can by anything like a partition on a local hard disk, a partition located on a remote SAN disk, a USB key or whatever else that could offer a storage space (so yes, technically it could be possible to use an optical storage device accessed in packet writing mode). The storage space on a physical volumes is divided (and managed) in small units called '''Physical Extents''' (or ''PE''). Just to give an analogy if you are a bit familiar with RAID, PE are a bit like RAID stripes.
* First, to perform edits on the wiki, you must {{CreateAccount}} and log in.
* '''Volume Groups (or ''VG'')''': a group of at least one PV. VG are '''named''' entities and will appear in the system via the device mapper as '''/dev/''volume-group-name'''''.
* You can create a new page by navigating to http://www.funtoo.org/New_Page_Name. Underscores are the equivalent of spaces. Then select "Create" under the "Actions" menu.
* '''Logical Volumes (or ''LV'')''': a '''named''' division of a volume group in which a filesystem is created and that can be mounted in the VFS. Just for the record, just as for the PE in PV, a LV is managed as chucks known as Logical Extents (or ''LE''). Most of the time those LE are hidden to the system administrator due to a 1:1 mapping between them and the PE lying be just beneath but a cool fact to know about LEs is that they can be spread over PV just like RAID stripes in a RAID-0 volume. However, researches done on the Web tends to demonstrate system administrators prefer to build RAID volumes with mdadm than use LVM over them for performance reasons.
* Whether creating a new page or editing an existing page by clicking "Edit", you will be presented with Web-based text editor that allows you to modify the ''wikitext'' of the page. The wikitext is rendered to produce the document you see when you view the page normally.
* Another fun thing you can do is click on your name under the "Account" menu once you have logged in. This will bring you to your "User" page. Then click "Create with Form" unde the "Actions" menu and enter your geographic and other information. This will allow you to be displayed on our [[Usermap]] and will also allow your full name to be displayed on [[:Category:Ebuilds|Ebuild pages]] for which you are an author. It's generally a good idea to do this.
In short words: LVM logical volumes (LV) are containers that can hold a single filesystem and which are created inside a volume group (VG) itself composed by an aggregation of at least one physical volumes (PV) themselves stored on various media (usb key, harddisk partition and so on). The data is stored in chunks spread over the various PV.
{{tip|The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.}}
{{fancynote|Retain what PV, VG and LV means as we will use those abbreviations in the rest of this article.}}
=== Paragraphs ===
= Your first tour of LVM =
To create a new paragraph, insert a blank line between two lines of text. If a blank line doesn't exist between two lines of wikitext, they will be combined into a single flowing paragraph.
== Physical volumes creation ==
If you leave leading whitespace at the beginning of a line, MediaWiki will render it as pre-formatted text. Beware of this. Here's an example:
{{fancynote|We give the same size to all volumes for the sake of the demonstration. This is not mandatory and be possible to have mixed sizes PV inside a same VG. }}
foobar
To start with, just create three raw disk images:
This can rear its ugly head when specifying template parameters, so you will get this:
<pre>
{{note| ugh!}}
# dd if=/dev/zero of=/tmp/hdd1.img bs=2G count=1
# dd if=/dev/zero of=/tmp/hdd2.img bs=2G count=1
# dd if=/dev/zero of=/tmp/hdd3.img bs=2G count=1
</pre>
and associate them to a loopback device:
...instead of this:
<pre>
{{note|This looks much better!}}
# losetup -f
/dev/loop0
# losetup /dev/loop0 /tmp/hdd1.img
# losetup /dev/loop1 /tmp/hdd2.img
# losetup /dev/loop2 /tmp/hdd3.img
</pre>
Okay nothing really exciting there, but wait the fun is coming! First check that '''sys-fs/lvm2''' is present on your system and emerge it if not. At this point, we must tell you a secret: although several articles and authors uses the taxonomy "LVM" it denotes "LVM version 2" or "LVM 2" nowadays. You must know that LVM had, in the old good times (RHEL 3.x and earlier), a previous revision known as "LVM version 1". LVM 1 is now considered as an extincted specie and is not compatible with LVM 2, although LVM 2 tools maintain a backward compatibility.
=== Page and Section Capitalization ===
The very frst step in LVM is to create the physical devices or ''PV''. "Wait create ''what''?! Aren't the loopback devices present on the system?" Yes they are present but they are empty, we must initialize them some metadata to make them usable by LVM. This is simply done by:
In general, capitalize all words in page names and section heading except:
* Articles: a, an, the
* Coordinating Conjunctions: and, but, or, for, nor, etc.
* Prepositions (fewer than five letters): on, at, to, from, by, etc.
<pre>
=== Document Hierarchy ===
# pvcreate /dev/loop0
Physical volume "/dev/loop0" successfully created
# pvcreate /dev/loop1
Physical volume "/dev/loop1" successfully created
# pvcreate /dev/loop2
Physical volume "/dev/loop2" successfully created
</pre>
It is absolutely normal that nothing in particular is printed at the output of each command but we assure you: you have three LVM PVs. You can check them by issuing:
Use section headings to create a document hierarchy for your page. These will define the table of contents that appears at the top of the wiki page. Create chapters, sections and sub-sections as follows:
<pre>
<pre>= Page Title =
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 lvm2 a- 2.00g 2.00g
/dev/loop1 lvm2 a- 2.00g 2.00g
/dev/loop2 lvm2 a- 2.00g 2.00g
</pre>
== Chapter Title ==
Some good information there:
=== Section Title ===
* PV: indicates the physical path the PV lies on
* VG indicates the VG the PV belongs to. At this time, we didn't created any VG yet and the column remains empty.
* Fmt: indicates the format of the PV (here it says we have a LVM version 2 PV)
* Attrs: indicates some status information, the 'a' here just says that the PV is accessible.
* PSize and PFree: indicates the PV size and the amount of remaining space for this PV. Here we have three empty PV so it bascially says "2 gigabytes large, 2 out of gigabytes free"
It is now time to introduce you to another command: '''pvdisplay'''. Just run it without any arguments:
==== SubSection Title ====
<pre>
pvdisplay
"/dev/loop0" is a new physical volume of "2.00 GiB"
--- NEW Physical volume ---
PV Name /dev/loop0
VG Name
PV Size 2.00 GiB
Allocatable NO
PE Size 0
Total PE 0
Free PE 0
Allocated PE 0
PV UUID b9i1Hi-llka-egCF-2vU2-f7tp-wBqh-qV4qEk
"/dev/loop1" is a new physical volume of "2.00 GiB"
--- NEW Physical volume ---
PV Name /dev/loop1
VG Name
PV Size 2.00 GiB
Allocatable NO
PE Size 0
Total PE 0
Free PE 0
Allocated PE 0
PV UUID i3mdBO-9WIc-EO2y-NqRr-z5Oa-ItLS-jbjq0E
"/dev/loop2" is a new physical volume of "2.00 GiB"
--- NEW Physical volume ---
PV Name /dev/loop2
VG Name
PV Size 2.00 GiB
Allocatable NO
PE Size 0
Total PE 0
Free PE 0
Allocated PE 0
PV UUID dEwVuO-a5vQ-ipcH-Rvlt-5zWt-iAB2-2F0XBf
</pre>
</pre>
The third three lines of each PV shows:
{{Note|By default, Table of Contents is disabled on the Funtoo wiki. If you would like to enable the TOC, you can place a <code><nowiki>__TOC__</nowiki></code> on a blank line where you'd like the Table of Contents to appear, or place <code><nowiki>__FORCETOC__</nowiki></code> on a blank line anywhere in the wikitext to force the TOC to appear at the top of the page.}}
* what is the storage device beneath a PV
* the VG it is tied to
* the size of this PV.
''Allocatable'' indicates whether the PV is used to store data. As the PV is not a member of a VG, it cannot not be used (yet) hence the "NO" shown. Another set of information is the lines starting with ''PE''. ''PE'' stands for ''' ''Physical Extents'' ''' (data stripe) and is the finest granularity LVM can manipulate. The size of a PE is "0" here because we have a blank PV however it typically holds 32 MB of data. Following ''PE Size'' are ''Total PE'' which show the the total '''number''' of PE available on this PV and ''Free PE'' the number of PE remaining available for use. ''Allocated PE'' just show the difference between ''Total PE'' and ''Free PE''.
The latest line (''PV UUID'') is a unique identifier used internally by LVM to name the PV. You have to know that it exists because it is sometimes useful when having to recover from corruption or do weird things with PV however most of the time you don't have to worry about its existence.
{{fancynote|It is possible to force how LVM handles the alignments on the physical storage. This is useful when dealing with 4K sectors drives that lies on their physical sectors size. Refer to the manual page. }}
== Volume group creation ==
We have the blank PV at this time but to make them a bit more usable for storage we must tell to LVM how they are grouped to form a VG (storage pool) where LV will be created. A nice aspect of VGs resides in the fact that they are not "written in the stone" once created: you can still add, remove or exchange PV (in the case the device the PV is stored on fails for example) inside a VG at a later time. To create our first volume group named ''vgtest'':
Just like we did before with PV, we can get a list of what are the VG known by the system. This is done through the command '''vgs''':
In general, when creating new documents, it's best to use level-3 (three "="'s) Section Titles to break up content. Level-2 Section Titles are best used for major sections of larger documents. Use them infrequently. Level-1 Section Titles generally do not need to be used.
<pre>
=== Links ===
# vgs
VG #PV #LV #SN Attr VSize VFree
vgtest 3 0 0 wz--n- 5.99g 5.99g
</pre>
'''vgs''' show you a tabluar view of information:
Internal links to other wiki pages can be specified as <tt><nowiki>[[pagename]]</nowiki></tt>. To specify an alternate name for the link, use <tt><nowiki>[[pagename|my link name]]</nowiki></tt>.
* '''VG:''' the name of the VG
* '''#PV:''' the number of PV composing the VG
* '''#LV:''' the number of logical volumes (LV) located inside the VG
* '''Attrs:''' a status field. w, z and n here means that VG is:
** '''w:''' '''w'''ritable
** '''z:''' resi'''z'''able
** '''n:''' using the allocation policy '''''n'''ormal'' (tweaking allocation policies is beyond the scope of this article, we will use the default value ''normal'' in the rest of this article)
* VSize and VFree gives statistics on how full a VG is versus its size
Note the dashes in ''Attrs'', they mean that the attribute is not active:
For external links, use <tt><nowiki>[http://funtoo.org my link]</nowiki></tt> to specify a URL. If you want the URL to appear in the wikitext, you can specify it without brackets: http://forums.funtoo.org.
* First dash (3rd position) indicates if the VG would have been exported (a 'x' would have been showed at this position in that case).
* Second dash (4th position) indicates if the VG would have been partial (a 'p' would have been showed at this position in that case).
* Third dash (rightmost position) indicates if the VG is a clustered (a 'c' would have been showed at this position in that case).
Exporting a VG and clustered VG are a bit more advanced aspects of LVM and won't be covered here especially the clustered VGs which are used in the case of a shared storage space used in a cluster of machines. Talking about clustered VGs management in particular would require and entire article in itself. '''For now the only detail you have to worry about those dashes in ''Attrs'' is to see a dash at the 4th position of ''Attrs'' instead of a ''p'''''. Seeing ''p'' there would be a bad news: the VG would have missing parts (PV) making it not usable.
=== Lists ===
{{fancynote|In the exact same manner you can see a detailed information about physical volumes with '''pvdisplay''', you can see detailed information of a volume group with '''vgdisplay'''. We will demonstrate that latter command in the paragraphs to follow.}}
MediaWiki supports a number of list formats:
Before leaving the volume group aspect, do you remember the '''pvs''' command shown in the previous paragraphs? Try it gain:
* Unordered List
* Unordered Item 2
** Unordered sub-item
<pre>
# Ordered List
# pvs
# Ordered Item 2
PV VG Fmt Attr PSize PFree
## Ordered sub-item
/dev/loop0 vgtest lvm2 a- 2.00g 2.00g
/dev/loop1 vgtest lvm2 a- 2.00g 2.00g
/dev/loop2 vgtest lvm2 a- 2.00g 2.00g
</pre>
Now it shows the VG our PVs belong to :-)
;Term: This is called a "definition list". It is used when defining various terms.
== Logical volumes creation ==
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:
Now the final steps: we will create the storage areas (logical volumes or ''LV'') inside the VG where we will then create filesystems on. Just like a VG has a name, a LV has also a name which is unique in the VG.
<blockquote>
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, the largest with 1.2 billion unique visitors."[10]
</blockquote>
{{fancynote|Two LV can be given the same name as long as they are located on a different VG.}}
=== Literal Text and HTML Symbols ===
To divide our VG like below:
Here is wikitext for the section above, which I am displaying by placing the literal wikitext between a <pre> and </pre> tag. If you want to disable wikitext processing for an inline span of text, use <nowiki> and </nowiki>. If you want to print out a tag literally, use &#60; and &#62; (In the wikitext, I used &amp;#60; and &amp;#62 to display these!)
* lvdata1: 2 GB
* lvdata2: 1 GB
* lvdata3 : 10% of the VG size
* lvdata4 : All of remaining free space in the VG
We use the following commands (notice the capital 'L' and the small 'l' to declare absolute or relative sizes):
<pre>
<pre>
# lvcreate -n lvdata1 -L 2GB vgtest
* Unordered List
Logical volume "lvdata1" created
* Unordered Item 2
# lvcreate -n lvdata2 -L 1GB vgtest
** Unordered sub-item
Logical volume "lvdata2" created
# lvcreate -n lvdata3 -l 10%VG vgtest
Logical volume "lvdata2" created
</pre>
What is going on so far? Let's check with the pvs/vgs counterpart known as '''lvs''':
# Ordered List
# Ordered Item 2
## Ordered sub-item
<pre>
;Term: This is called a "definition list". It is used when defining various terms.
Notice the size of ''lvdata3'', it is roughly 600MB (10% of 6GB). How much free space remains in the VG? Time to see what '''vgs''' and '''vgdisplay''' returns:
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:
<pre>
<blockquote>
# vgs
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access,
VG #PV #LV #SN Attr VSize VFree
free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers
vgtest 3 3 0 wz--n- 5.99g 2.39g
worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the
# vgdisplay
English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet
--- Volume group ---
comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York
VG Name vgtest
Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views
System ID
and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google,
Format lvm2
the largest with 1.2 billion unique visitors."[10]
Metadata Areas 3
</blockquote>
Metadata Sequence No 4
VG Access read/write
VG Status resizable
MAX LV 0
Cur LV 3
Open LV 0
Max PV 0
Cur PV 3
Act PV 3
VG Size 5.99 GiB
PE Size 4.00 MiB
Total PE 1533
Alloc PE / Size 921 / 3.60 GiB
Free PE / Size 612 / 2.39 GiB
VG UUID baM3vr-G0kh-PXHy-Z6Dj-bMQQ-KK6R-ewMac2
</pre>
</pre>
Basically it say we have 1533 PE (chunks) available for a total size of 5.99 GiB. On those 1533, 921 are used (for a size of 3.60 GiB) and 612 remains free (for a size of 2.39 GiB). So we expect to see lvdata4 having an approximative size of 2.4 GiB. Before creating it, have a look at some statistics at the PV level:
=== Linking to Packages ===
<pre>
To link to a package page, use the <code>Package</code> template:
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgtest lvm2 a- 2.00g 0
/dev/loop1 vgtest lvm2 a- 2.00g 404.00m
/dev/loop2 vgtest lvm2 a- 2.00g 2.00g
# pvdisplay
<pre><nowiki>
--- Physical volume ---
{{Package|sys-apps/portage}}
PV Name /dev/loop0
</nowiki></pre>
VG Name vgtest
PV Size 2.00 GiB / not usable 4.00 MiB
Allocatable yes (but full)
PE Size 4.00 MiB
Total PE 511
Free PE 0
Allocated PE 511
PV UUID b9i1Hi-llka-egCF-2vU2-f7tp-wBqh-qV4qEk
--- Physical volume ---
PV Name /dev/loop1
VG Name vgtest
PV Size 2.00 GiB / not usable 4.00 MiB
Allocatable yes
PE Size 4.00 MiB
Total PE 511
Free PE 101
Allocated PE 410
PV UUID i3mdBO-9WIc-EO2y-NqRr-z5Oa-ItLS-jbjq0E
--- Physical volume ---
PV Name /dev/loop2
VG Name vgtest
PV Size 2.00 GiB / not usable 4.00 MiB
Allocatable yes
PE Size 4.00 MiB
Total PE 511
Free PE 511
Allocated PE 0
PV UUID dEwVuO-a5vQ-ipcH-Rvlt-5zWt-iAB2-2F0XBf
</pre>
Quite interesting! Did you notice? The first PV is full, the second is more or less full and the third is empty. This is due to the allocation policy used for the VG: it fills its first PV then its second PV and then its third PV (this, by the way, gives you a chance to recover from a dead physical storage if by luck none of your PE was present on it).
This template will create a link to the official wiki page for sys-apps/portage, and render using the official "English" page name, as follows:
It is now time to create our last LV, again notice the small 'l' to specify a relative size:
{{Package|sys-apps/portage}}
<pre>
If you specify a yet-to-be-documented ebuild, it will render like this (which is okay -- it will encourage people to document it):
Now the $100 question: if '''pvdisplay''' and '''vgdisplay''' commands exist, does command named '''lvdisplay''' exist as well? Yes absolutely! Indeed the command sets are coherent between abstraction levels (PV/VG/LV) and they are named in the exact same manner modulo their first 2 letters:
{{Package|sys-foo/undocumented-ebuild}}
* PV: pvs/pvdisplay/pvchange....
=== Tables ===
* VG: vgs/vgdisplay/vgchange....
* LG: lvs/lvdisplay/lvchange....
Back to our '''lvdisplay''' command, here is how it shows up:
Instead of using traditional MediaWiki table wikitext, use the following format:
Nothing extremely useful to comment for an overview beyond showing at the exception of two things:
This wil render as follows:
# '''LVs are accessed via the device mapper''' (see the lines starting by ''LV Name'' and notice how the name is composed). So '''lvdata1''' will be accessed via ''/dev/vgtest/lvdata1'', ''lvdata2'' will be accessed via ''/dev/vgtest/lvdata2'' and so on.
# just like PV are managed in sets of data chunks (the so famous Physical Extents or PEs), LVs are managed in a set of data chunks known as Logical Extents or LEs. Most of the time you don't have to worry about the existence of LEs because they fits withing a single PE although it is possible to make them smaller hence having several LE within a single PE. Demonstration: if you consider the first LV, '''lvdisplay''' says it has a size of 2 GiB and holds 512 logical extents. Dividing 2GiB by 512 gives 4 MiB as the size of a LE which is the exact same size used for PEs as seen when demonstrating the '''pvdisplay''' command some paragraphs above. So in our case we have a 1:1 match between a LE and the underlying PE.
Oh another great point to underline: you can display the PV in relation with a LV :-) Just give a special option to '''lvdisplay''':
{{tip|This table syntax has an added benefit of creating a responsive table that renders properly on mobile devices.}}
# lvdisplay -m
--- Logical volume ---
LV Name /dev/vgtest/lvdata1
VG Name vgtest
(...)
Current LE 512
Segments 2
(...)
--- Segments ---
Logical extent 0 to 510:
Type linear
Physical volume /dev/loop0
Physical extents 0 to 510
Logical extent 511 to 511:
Type linear
Physical volume /dev/loop1
Physical extents 0 to 0
--- Logical volume ---
LV Name /dev/vgtest/lvdata2
VG Name vgtest
(...)
Current LE 256
Segments 1
(...)
--- Segments ---
Logical extent 0 to 255:
Type linear
Physical volume /dev/loop1
Physical extents 1 to 256
--- Logical volume ---
LV Name /dev/vgtest/lvdata3
VG Name vgtest
(...)
Current LE 153
Segments 1
(...)
--- Segments ---
Logical extent 0 to 152:
Type linear
Physical volume /dev/loop1
Physical extents 257 to 409
--- Logical volume ---
LV Name /dev/vgtest/lvdata4
VG Name vgtest
(...)
Current LE 612
Segments 2
(...)
--- Segments ---
Logical extent 0 to 510:
Type linear
Physical volume /dev/loop2
Physical extents 0 to 510
Logical extent 511 to 611:
Type linear
Physical volume /dev/loop1
Physical extents 410 to 510
</pre>
To go one step further let's analyze a bit how the PE are used: the first LV has 512 LEs (remember: one LE fits within one PE here so 1 LE = 1 PE). Amongst those 512 LEs, 511 of them (0 to 510) are stored on /dev/loop0 and the 512th LE is on /dev/loop1. Huh? Something seems to be wrong here, '''pvdisplay''' said that /dev/loop0 was holding 512 PV so why an extent has been placed on the second storage device? Indeed its not a misbehaviour and absolutely normal: LVM uses some metadata internally with regards the PV, VG and LV thus making some of storage space unavailable for the payload. This explains why 1 PE has been "eaten" to store that metadata. Also notice the linear allocation process: ''/dev/loop0'' has been used, then when being full ''/dev/loop1'' has also been used then the turn of /''dev/loop2'' came.
It is possible to use the following CSS classes with <code>tr</code> (rows) and <code>td/th</code> elements to color them as desired:
Now everything is in place, if you want just check again with '''vgs/pvs/vgdisplay/pvdisplay''' and will notice that the VG is now 100% full and all of the underlying PV are also 100% full.
{{TableStart}}
<tr class="active"><td>Class Name</td></tr>
<tr class="success"><td>success</td></tr>
<tr class="info"><td>info</td></tr>
<tr class="warning"><td>warning</td></tr>
<tr class="active"><td>active</td></tr>
<tr class="danger"><td>danger</td></tr>
{{TableEnd}}
== Filesystems creation and mounting ==
=== Displaying Source Code ===
Now we have our LVs it could be fun if we could do something useful with them. In the case you missed it, LVs are accessed via the device mapper which uses a combination of the VG and LV names thus:
To display source code, use can use the file template, specifying a <tt>lang=</tt> parameter:
* lvdata1 is accessible via /dev/vgtest/lvdata1
* lvdata2 is accessible via /dev/vgtest/lvdata2
* and so on!
Just like any traditional storage device, the newly created LVs are seen as block devices as well just as if they were a kind of harddisk (don't worry about the "dm-..", it is just an internal block device automatically allocated by the device mapper for you):
brw-rw---- 1 root disk 253, 0 Dec 27 12:54 /dev/dm-0
brw-rw---- 1 root disk 253, 1 Dec 27 12:54 /dev/dm-1
brw-rw---- 1 root disk 253, 2 Dec 27 12:54 /dev/dm-2
brw-rw---- 1 root disk 253, 3 Dec 27 12:54 /dev/dm-3
</pre>
</pre>
So if LVs are block device a filesystem can be created on them just like if they were a real harddisk or hardisk partitions? Absolutely! Now let's create ext4 filesystems on our LVs:
The parameters {{c|name}} (filename), {{c|lang}} (language for syntax highlighting) and {{c|desc}} (Description, appearing as a caption) are optional. For a list of supported languages, see [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages this list].
Discarding device blocks: done
Filesystem label=
OS type: Linux
Block size=4096 (log=2)
Fragment size=4096 (log=2)
Stride=0 blocks, Stripe width=0 blocks
131072 inodes, 524288 blocks
26214 blocks (5.00%) reserved for the super user
First data block=0
Maximum filesystem blocks=536870912
16 block groups
32768 blocks per group, 32768 fragments per group
8192 inodes per group
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
# mkfs.ext4 /dev/vgtest/lvdata1
{{important|If you need to display the pipe ("{{!}}") character within the body of a file template, replace each "{{!}}" with <nowiki>{{!}}</nowiki> -- otherwise your file contents will not display properly. This is necessary because <nowiki>{{file}}</nowiki> is a template and the "{{!}}" character is used as a delimiter for arguments to the template.}}
(...)
# mkfs.ext4 /dev/vgtest/lvdata2
(...)
# mkfs.ext4 /dev/vgtest/lvdata3
(..)
</pre>
Once the creation ended we must create the mount points and mount the newly created filesystems on them:
=== Displaying Text File Contents ===
<pre>
For displaying the contents of non-programming language text files (like config files), you have two options. You can enclose your lines within <tt><pre></tt> tags, or use the new [[Template:File|file template]]. The file template is used like so:
/dev/mapper/vgtest-lvdata4 2.4G 100M 2.2G 5% /mnt/data04
</pre>
</pre>
Did you notice the device has changed? Indeed everything is in order, mount just uses another set of symlinks which point to the exact same block devices:
== Renaming a volume group and its logical volumes ==
=== Console ===
To display console output, use the <tt><console></tt> tag:
So far we have four LVs named lvdata1 to lvdata4 mounted on /mnt/data01 to /mnt/data04. It would be more adequate to :
# make the number in our LV names being like "01" instead of "1"
# rename our volume groupe to "vgdata" instead of "vgtest"
To show how dynamic is the LVM world, we will rename our VG and LV on the fly using two commands: '''vgrename''' for acting at the VG level and its counterpart '''lvrename''' to act at the LV level. Starting by the VG or the LVs makes strictly no difference, you can start either way and get the same result. In our example we have chosen to start with the VG:
For a root console:
<pre>
<pre>
# vgrename vgtest vgdata
<console>
Volume group "vgtest" successfully renamed to "vgdata"
###i## run a command as root
# lvrename vgdata/lvdata1 vgdata/lvdata01
</console>
Renamed "lvdata1" to "lvdata01" in volume group "vgdata"
# lvrename vgdata/lvdata2 vgdata/lvdata02
Renamed "lvdata2" to "lvdata02" in volume group "vgdata"
# lvrename vgdata/lvdata3 vgdata/lvdata03
Renamed "lvdata3" to "lvdata03" in volume group "vgdata"
# lvrename vgdata/lvdata4 vgdata/lvdata04
Renamed "lvdata4" to "lvdata04" in volume group "vgdata"
Sounds good, our VG and LVs have been renamed! What a command like ''mount'' will say?
{{important|1=
Note that we use a <tt>#</tt> prompt for <tt>root</tt> and a <tt>$</tt> prompt to denote a non-root user.}}
<pre>
{{important|The <tt>##i##</tt> text tags the rest of the line as being ''user input'' ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.}}
# mount
(...)
/dev/mapper/vgtest-lvdata1 on /mnt/data01 type ext4 (rw)
/dev/mapper/vgtest-lvdata2 on /mnt/data02 type ext4 (rw)
/dev/mapper/vgtest-lvdata3 on /mnt/data03 type ext4 (rw)
/dev/mapper/vgtest-lvdata4 on /mnt/data04 type ext4 (rw)
</pre>
Ooops... It is not exactly a bug, mount still shows the symlinks used at the time the LVs were mounted in the VFS and has not updated its information. However once again everything is correct because the underlying block devices (/dev/dm-0 to /dev/dm-3) did not changed at all. To see the right information the LVs must be unmounted and mounted again:
If you need to end highlighting of user input prior to the end of a line, use <code>##!i##</code> to mark the end of the highlighted area.
<pre>
The following special character sequences are also available:
# umount /mnt/data01
* <code>##g##</code> - Green
(...)
* <code>##y##</code> - Yellow
# umount /mnt/data04
* <code>##bl##</code> - Blue
# mount /dev/vgdata/lvdata01 /mnt/data01
* <code>##r##</code> - Red
(...)
* <code>##b##</code> - Bold
# mount /dev/vgdata/lvdata04 /mnt/data04
# mount
/dev/mapper/vgdata-lvdata01 on /mnt/data01 type ext4 (rw)
/dev/mapper/vgdata-lvdata02 on /mnt/data02 type ext4 (rw)
/dev/mapper/vgdata-lvdata03 on /mnt/data03 type ext4 (rw)
/dev/mapper/vgdata-lvdata04 on /mnt/data04 type ext4 (rw)
</pre>
{{fancynote|Using /dev/''volumegroup''/''logicalvolume'' or /dev/''volumegroup''-''logicalvolume'' makes no difference at all, those are two sets of symlinks pointing on the '''exact''' same block device. }}
Please use the above coloring options sparingly. It is sometimes nice to use them to get wiki console output to match the colors that are displayed on a Linux console. Also note that for every color above, there is a matching <code>##!(colorcode)##</code> option to turn color off prior to end of line.
Did you notice in the previous section we have never talked on topic like "create this partition at the beginning" or "allocate 10 sectors more". In LVM you do not have to worry about that kind of problematics: your only concern is more "Do I have the space to allocate a new LV or how can I extend an existing LV?". '''LVM takes cares of the low levels aspects for you, just focus on what you want to do with your storage space.'''
=== Informational Messages ===
Notes, warnings, tips, and important templates can be used for informational messages that need to be offset from the regular text flow:
The most common problem with computers is the shortage of space on a volume, most of the time production servers can run months or years without requiring a reboot for various reasons (kernel upgrade, hardware failure...) however they regularly requires to extend their storage space because we do generate more and more data as the time goes. With "traditional" approach like fiddling directly with hard drives partitions, storage space manipulation can easily become a headache mainly because it requires coherent copy to be made and thus application downtimes. Don't expect the situation to be more enjoyable with a SAN storage rather a directly attached storage device... Basically the problems remains the same.
<pre>{{note|this is a note}}</pre>
{{note|this is a note}}
== Expanding a storage space ==
<pre>{{important|this is important}}</pre>
{{important|this is important}}
The most common task for a system administrator is to expand the available storage space. In the LVM world this implies:
<pre>{{warning|this is a warning}}</pre>
* Creating a new PV
{{warning|this is a warning}}
* Adding the PV to the VG (thus extending the VG capacity)
* Extending the existing LVs or create new ones
* Extending the structures of the filesystems located on a LV in the case a LV is extended (Not all of the filesystems around support that capability).
=== Bringing a new PV in the VG ===
<pre>{{tip|this is a tip}}</pre>
{{tip|this is a tip}}
In the exact same manner we have created our first PV let's create our additional storage device, associate it to a loopback device and then create a PV on it:
Note that these templates used to be called <code>fancynote</code>, <code>fancytip</code>, etc. The "fancy" names have been deprecated but will still be supported for the forseeable future.
=== Kernelop ===
To display kernel configuration options, we encourage you to use the <tt>kernelop</tt> template. To use the <tt>kernelop</tt> template, create an entry similar to the following example:
<pre>
<pre>
# dd if=/dev/zero of=/tmp/hdd4.img bs=2G count=1
{{kernelop|title=foo,bar|desc=
# losetup /dev/loop3 /tmp/hdd4.img
kernel options pasted from "make menuconfig"
# pvcreate /dev/loop3
}}
</pre>
</pre>
A '''pvs''' should report the new PV with 2 GB of free space:
{{note|Kernelop is colored blue to slightly resemble the blueish background from <tt>make menuconfig</tt>.}}
<pre>
Adding this entry will give you the following output:
# pvs
{{kernelop|title=foo,bar|desc=
PV VG Fmt Attr PSize PFree
kernel options
/dev/loop0 vgdata lvm2 a- 2.00g 0
}}
/dev/loop1 vgdata lvm2 a- 2.00g 0
/dev/loop2 vgdata lvm2 a- 2.00g 0
/dev/loop3 lvm2 a- 2.00g 2.00g
</pre>
Excellent! The next step consist of adding this newly created PV inside our VG ''vgdata'', this is where the '''vgextend''' command comes at our rescue:
Here's a more concrete example:
{{kernelop|title=File systems|desc=
<pre>
<M> Second extended fs support
# vgextend vgdata /dev/loop3
[ ] Ext2 extended attributes
Volume group "vgdata" successfully extended
[ ] Ext2 execute in place support
# vgs
<M> Ext3 journalling file system support
VG #PV #LV #SN Attr VSize VFree
}}
vgdata 4 4 0 wz--n- 7.98g 2.00g
</pre>
Great, ''vgdata'' is now 8 GB large instead of 6 GB and have 2 GB of free space to allocate to either new LVs either existing LVs.
=== Extending the LV and its filesystem ===
Bringing new LV would demonstrate nothing more nevertheless extending our existing LVs is much more interesting. How can we use our 2GB extra free space? We can, for example, split it in two allocating a 50% to our first (''lvdata01'') and third (''lvdata03'') LV adding 1GB of space to both. The best of the story is that operation is very simple and is realized with a command named '''lvextend''':
<pre>
# lvextend vgdata/lvdata01 -l +50%FREE
Extending logical volume lvdata01 to 3.00 GiB
Logical volume lvdata01 successfully resized
# lvextend vgdata/lvdata03 -l +50%FREE
Extending logical volume lvdata03 to 1.10 GiB
Logical volume lvdata03 successfully resized
</pre>
Ouaps!! We did a mistake there: lvdata01 has the expected size (2GB + 1GB for a grand total of 3 GB) but lvdata03 only grown of 512 MB (for a grand total size of 1.1 GB). Our mistake was obvious: once the first gigabyte (50% of 2GB) of extra space has been given to lvdata01, only one gigabyte remained free on the VG thus when we said "allocate 50% of the remaining gigabyte to ''lvdata03''" LVM added only 512 MB leaving the other half of this gigabyte unused. The '''vgs''' command can confirm this:
Examples of usage:
* [[Package:AMD Catalyst Video Drivers]]
* [[Package:ACPI Daemon]]
* [[Microcode]]
<pre>
=== Discussion Pages ===
# vgs
VG #PV #LV #SN Attr VSize VFree
vgdata 4 4 0 wz--n- 7.98g 512.00m
</pre>
Nevermind about that voluntary mistake we will keep that extra space for a later paragraph :-) What happened to the storage space visible from the operating system?
In MediaWiki, every "regular" wiki page has a corresponding "Talk" or "Discussion" page which has a page name prefixed by "Talk:" -- you can get to this page by going to the "Action" menu, and then choosing the "Discussion" menu item. These talk pages are typically used to discuss the edits that are going on in the "main" wiki page. The problem with talk pages is that they are kind of a pain to use. However, we have a way to fix that. If you want to enable a DISQUS-based mini-forum on a talk page, insert the following wikitext on the Talk page:
Obviously resizing a LV does not "automagically" resize the filesystem structures to take into account the new LV size making that step part of our duty. Happily for us, ext3 can be resized and better it can be grown when mounted in the VFS. This is known as ''online resizing'' and a few others filesystems supports that capability, among them we can quote ext2 (ext3 without a journal), ext4 (patches integrated very recently as of Nov/Dec 2011), XFS, ResiserFS and BTRFS. To our knowledge, only BTRFS support both online resizing '''and''' online shrinking as of Decembrer 2011, all of the others require a filesystem to be unmounted first before being shrunk.
...and presto! You will now have DISQUS-powered mini-forums to discuss whatever you want about your wiki page.
{{fancynote|Consider using the option -r when invoking lvextend, it asks the command to perform a filesystem resize.}}
== Marking Pages as Needing Updates ==
Now let's extend (grow) the ext3 filesystem located on lvdata01. As said above, ext3 support online resizing hence we do not need to kick it out of the VFS first:
If you find outdated wiki content, but you don't have the time or ability to update it, add one of the following templates to the wikitext of the page. This will add the page to the [[:Category:Needs Updates|Needs Updates Category]] so we can identify pages that need updating:
<pre>
<pre>
# resize2fs /dev/vgdata/lvdata01
{{PageNeedsUpdates}}
resize2fs 1.42 (29-Nov-2011)
{{SectionNeedsUpdates}}
Filesystem at /dev/vgdata/lvdata01 is mounted on /mnt/data01; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 1
Performing an on-line resize of /dev/vgdata/lvdata01 to 785408 (4k) blocks.
The filesystem on /dev/vgdata/lvdata01 is now 785408 blocks long.
''Et voila!'' Our LV has now plenty of new space usable :-) '''We do not bother about ''how'' the storage is organized by LVM amongst the underlying storage devices and it is not our problem after all. We only worry about having our storage requirements being satisfied without any further details. From our point of view everything is seen just as if we were manipulating a single storage device subdivided in several partitions of a dynamic size and always organized in a set of contiguous blocks.'''
Now let's shuffle the cards a bit more: when we examined how the LEs of our LVs were allocated, we saw that ''lvdata01'' (named lvdata1 at this time) consisted of 512 LEs or 512 PEs (because of the 1:1 mapping between those) spread over two PVs. As we have extended it to use an additional PV, we should see it using 3 segments:
Examples of usage:
* [[UEFI Install Guide]]
* [[Package:MediaWiki]]
* [[Clang]]
* Segment 1: located on the PV stored on /dev/loop0 (LE/PE #0 to #510)
=== Inline Code ===
* Segment 2: located on the PV stored on /dev/loop1 (LE/PE #511)
* Segment 3: located on the PV stored on /dev/loop1 (LE/PE #512 and followers)
Is it the case? Let's check:
To emphasize commands, and other technical jargon when they appear inline in a paragraph, use the <nowiki>{{c}}</nowiki> template. When referencing files, use the <nowiki>{{f}}</nowiki> template.
<pre>
<pre>
# lvdisplay -m vgdata/lvdata01
The {{f|/etc/fstab}} file is an important one. Another important file is {{f|/boot/grub/grub.cfg}}. The {{c|emerge}} command is really nifty.
--- Logical volume ---
LV Name /dev/vgdata/lvdata01
VG Name vgdata
LV UUID fT22is-cmSL-uhwM-zwCd-jeIe-DWO7-Hkj4k3
LV Write Access read/write
LV Status available
# open 1
LV Size 3.00 GiB
Current LE 767
Segments 3
Allocation inherit
Read ahead sectors auto
- currently set to 256
Block device 253:0
--- Segments ---
Logical extent 0 to 510:
Type linear
Physical volume /dev/loop0
Physical extents 0 to 510
Logical extent 511 to 511:
Type linear
Physical volume /dev/loop1
Physical extents 0 to 0
Logical extent 512 to 766:
Type linear
Physical volume /dev/loop3
Physical extents 0 to 254
</pre>
</pre>
Bingo! Note that if it is true here (LVM uses linear allocation) would not be true in the general case.
This example produces the following output:
{{fancywarning|'''Never mix a local storage device with a SAN disk within the same volume group''' and especially if that later is your system volume. It will bring you a lot of troubles if the SAN disk goes offline or bring weird performance fluctuations as PEs allocated on the SAN will get faster response times than those located on a local disk. }}
The {{f|/etc/fstab}} file is an important one. Another important file is {{f|/boot/grub/grub.cfg}}. The {{c|emerge}} command is really nifty.
== Shrinking a storage space ==
{{important|1=
The <tt> tag has been deprecated for the purpose of tagging inline code, to conform with HTML5, and the previous use of the <code> tag is discouraged. It is more maintainable to use the <nowiki>{{c}}</nowiki> template. }}
On some occasions it can be useful to reduce the size of a LV or the size of the VG itself. The principle is similar to what has been demonstrated in the previous section:
=== Slideshow ===
# umount the filesystem belong to the LV to be processed (if your filesystem does not support online shrinking)
Any page has the capability of displaying a slideshow. Adding a slideshow to a page involves three steps:
# reduce the filesystem size (if the LV is not to be flushed)
# reduce the LV size - OR - remove the LV
# remove a PV from the volume group if no longer used to store extents
The simplest case to start with is how a LV can be removed: a good candidate for removal is ''lvdata03'', we failed to resize it and the better would be to scrap it. First unmount it:
Noticed the little change with '''lvs'''? It lies in the ''Attr'' field: once the ''lvdata03'' has been unmounted, '''lvs''' tells us the LV is not '''o'''pened anymore (the little o at the rightmost position has been replaced by a dash). The LV still exists but nothing is using it.
To upload images, head to [[Special:Upload]] and upload a file. It is highly recommended to upload JPEG format images in high resolution -- MediaWiki will handle scaling JPEG automatically, saving bandwidth, but does not do this for PNG. Make sure that all images you upload have the same dimensions. When you upload, make note of the '''Destination Filename''' field -- this is the name that the upload will use when you reference it in your slide. It is recommended that you choose a simple descriptive name ending in ".jpg" for the '''Destination Filename'''.
To remove ''lvdata03'' use the command '''lvremove''' and confirm the removal by entering 'y' when asked:
==== Define Slides ====
<pre>
Once images have been uploaded, you must define slides. To define slides on a page, you enter special semantic information about the slide on the page that it will be displayed, in the following format:
# lvremove vgdata/lvdata03
Do you really want to remove active logical volume lvdata03? [y/n]: y
Notice the 1.60 of space has been freed in the VG. What can we do next? Shrinking ''lvdata04'' by 50% giving roughly 1.2GB or 1228MB (1.2*1024) of its size could be a good idea so here we go. First we need to umount the filesystem from the VFS because ext3 '''does not support''' online shrinking.
<pre><nowiki>
{{#subobject:|slideIndex=0|slideCaption=
== Wikitext Here ==
This is a fantastic slide!
|slideImage=File:Fruit.jpg|slideLink=PageName}}
</nowiki></pre>
<pre>
Here are some important instructions regarding defining slides:
Not very practical indeed, we can tell '''lvreduce''' to handle the underlying filesystem shrinkage for us. Let's shrink again this time giving a 1 GB volume (1024 MB) in absolute size:
* <code>slideIndex</code> must be 0 for the first slide, 1 for the second slide, etc. Numbers must be unique and incrementing from zero, and not doing this will result in slideshow display errors (but can be easily fixed by correcting the wikitext.)
* <code>slideCaption=</code> can contain wikitext, such as headings and links. The best way to enter <code>slideCaption</code> is as above -- type a literal <code>slideCaption=</code>, followed by enter, then specify your wikitext, and terminate the caption by a single pipe character on the following line. Pipe characters are used to separate arguments from each other.
* Specify your image name in the <code>slideImage</code> field. Your slideImage will have a name of <code>File:myname.jpg</code>, where <code>myname.jpg</code> is the '''Destination Filename''' you used when uploading the image.
* An optional parameter called <code>slideLink=</code> can be provided to allow the image to be clickable and link to another wiki page. If it is omitted, then the image will not be clickable.
Wow, we have near 3 GB of free space inside, a bit more than one of our PV. It could be great if we can free one of the those and of course LVM gives you the possibility to do that. Before going further, let's check what happened at the PVs level:
<pre>
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 0
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 a- 2.00g 1020.00m
/dev/loop3 vgdata lvm2 a- 2.00g 1.00g
</pre>
Did you noticed? 1 GB of space has been freed on the last PV (/dev/loop3) since ''lvdata04'' has been shrunk not counting the space freed on ''/dev/loop1'' and ''/dev/loop2'' after the removal of lvdata02.
Next steo: can we remove a PV directly (the command to remove a PV from a VG is '''vgreduce''')?
<pre>
# vgreduce vgdata /dev/loop0
Physical volume "/dev/loop0" still in use
</pre>
Of course not, all of our PVs supports the content of our LVs and we must find a manner to move all of the PE (physical extents) actually hold by the PV /dev/loop0 elsewhere withing the VG. But wait a minute, the victory is there yet: we do have some free space in the /dev/loop0 and we will get more and more free space in it as the displacement process will progress. What is going to happen if, from a concurrent session, we create others LV in ''vgdata'' at the same time the content of /dev/loop0 is moved? Simple: it can be filled again with the PEs newly allocated.
So before proceeding to the displacement of what ''/dev/loop0'' contents, we must say to LVM: "please don't allocate anymore PEs on ''/dev/loop0''". This is achieved via the parameter ''-x'' of the command '''pvchange''':
<pre>
# pvchange -x n /dev/loop0
Physical volume "/dev/loop0" changed
1 physical volume changed / 0 physical volumes not changed
</pre>
The value ''n'' given to ''-x'' marks the PV as ''unallocable'' (i.e. not usable for future PE allocations). Let's check again the PVs with '''pvs''' and '''pvdisplay''':
<pre>
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 -- 2.00g 0
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 a- 2.00g 1020.00m
/dev/loop3 vgdata lvm2 a- 2.00g 1.00g
# pvdisplay /dev/loop0
--- Physical volume ---
PV Name /dev/loop0
VG Name vgdata
PV Size 2.00 GiB / not usable 4.00 MiB
Allocatable NO
PE Size 4.00 MiB
Total PE 511
Free PE 0
Allocated PE 511
PV UUID b9i1Hi-llka-egCF-2vU2-f7tp-wBqh-qV4qEk
</pre>
Great news here, the ''Attrs'' field shows a dash instead of 'a' at the leftmost position meaning the PV is effectively ''not allocatable''. However '''marking a PV not allocatable does not wipe the existing PEs stored on it'''. In other words, it means that data present on the PV remains '''absolutely intact'''. Another positive point lies the remaining capacities of the PVs composing ''vgdata'': the sum of free space available on ''/dev/loop1'', ''/dev/loop2'' and ''/dev/loop3'' is 3060MB (1016MB + 1020MB + 1024MB) so largely sufficient to hold the 2048 MB (2 GB) actually stored on the PV ''/dev/loop0''.
Now we have frozen the allocation of PEs on /dev/loop0 we can make LVM move all of PEs located in this PV on the others PVs composing the VG ''vgdata''. Again, we don't have to worry about the gory details like where LVM will precisely relocate the PEs actually hold by ''/dev/loop0'', our '''only''' concerns is to get all of them moved out of ''/dev/loop0''. That job gets done by:
<pre>
# pvmove /dev/loop0
/dev/loop0: Moved: 5.9%
/dev/loop0: Moved: 41.3%
/dev/loop0: Moved: 50.1%
/dev/loop0: Moved: 100.0%
</pre>
We don't have to tell LVM the VG name because it already knows that ''/dev/loop0'' belongs to ''vgdata'' and what are the others PVs belonging to that VG usable to host the PEs coming from ''/dev/loop0''. It is absolutely normal for the process to takes some minutes (real life cases can go up to several hours even with SAN disks located on high-end storage hardware which is much more faster than local SATA or even SAS drive).
At the end of the moving process, we can see that the PV ''/dev/loop0'' is totally free:
<pre>
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 2.00g
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 a- 2.00g 0
/dev/loop3 vgdata lvm2 a- 2.00g 0
# pvdisplay /dev/loop0
--- Physical volume ---
PV Name /dev/loop0
VG Name vgdata
PV Size 2.00 GiB / not usable 4.00 MiB
Allocatable yes
PE Size 4.00 MiB
Total PE 511
Free PE 511
Allocated PE 0
PV UUID b9i1Hi-llka-egCF-2vU2-f7tp-wBqh-qV4qEk
</pre>
511 PEs free out of a maximum 511 PEs so all of its containt has been successfully spread on the others PVs (the volume is also still marked as "unallocatable", this is normal). Now it is ready to be detached from the VG ''vgdata'' with the help of '''vgreduce''' :
<pre>
# vgreduce vgdata /dev/loop0
Removed "/dev/loop0" from volume group "vgdata"
</pre>
What happened to ''vgdata''?
<pre>
# vgs
VG #PV #LV #SN Attr VSize VFree
vgdata 3 3 0 wz--n- 5.99g 1016.00m
</pre>
Its storage space falls to ~6GB! What would tell '''pvs'''?
<pre>
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 lvm2 a- 2.00g 2.00g
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 a- 2.00g 0
/dev/loop3 vgdata lvm2 a- 2.00g 0
</pre>
''/dev/loop0'' is now a standalone device detached from any VG. However it still contains some LVM metadata that remains to be wiped with the help of the '''pvremove''' command:
{{fancywarning|pvremove/pvmove '''do not destroy the disk content'''. Please *do* a secure erase of the storage device with ''shred'' or any similar tool before disposing of it. }}
<pre>
# pvdisplay /dev/loop0
"/dev/loop0" is a new physical volume of "2.00 GiB"
--- NEW Physical volume ---
PV Name /dev/loop0
VG Name
PV Size 2.00 GiB
Allocatable NO
PE Size 0
Total PE 0
Free PE 0
Allocated PE 0
PV UUID b9i1Hi-llka-egCF-2vU2-f7tp-wBqh-qV4qEk
# pvremove /dev/loop0
Labels on physical volume "/dev/loop0" successfully wiped
# pvdisplay /dev/loop0
No physical volume label read from /dev/loop0
Failed to read physical volume "/dev/loop0"
</pre>
Great! Things are just simple than that. In their day to day reality, system administrators drive their show in a extremely close similar manner: they do additional tasks like taking backups of data located on the LVs before doing any risky operation or plan applications shutdown periods prior starting a manipulation with a LVM volume to take extra precautions.
== Replacing a PV (storage device) by another ==
The principle a mix of what has been said in the above sections. The principle is basically:
# Create a new PV
# Associate it to the VG
# Move the contents of the PV to be removed on the remaining PVs composing the VG
# Remove the PV from the VG and wipe it
The strategy in this paragraph is to reuse ''/dev/loop0'' and make it replace ''/dev/loop2'' (both devices are of the same size, however we also could have used a bigger ''/dev/loop0'' as well).
Here we go! First we need to (re-)create the LVM metadata to make ''/dev/loop0'' usable by LVM:
<pre>
# pvcreate /dev/loop0
Physical volume "/dev/loop0" successfully created
</pre>
Then this brand new PV is added to the VG ''vgdata'' thus increasing its size of 2 GB:
<pre>
# vgextend vgdata /dev/loop0
Volume group "vgdata" successfully extended
# vgs
VG #PV #LV #SN Attr VSize VFree
vgdata 4 3 0 wz--n- 7.98g 2.99g
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 2.00g
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 a- 2.00g 0
/dev/loop3 vgdata lvm2 a- 2.00g 0
</pre>
Now we have to suspend the allocation of PEs on ''/dev/loop2'' prior to moving its PEs (and freeing some space on it):
<pre>
# pvchange -x n /dev/loop2
Physical volume "/dev/loop2" changed
1 physical volume changed / 0 physical volumes not changed
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 2.00g
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 -- 2.00g 0
/dev/loop3 vgdata lvm2 a- 2.00g 0
</pre>
Then we move all of the the PEs on ''/dev/loop2'' to the rest of the VG:
<pre>
# pvmove /dev/loop2
/dev/loop2: Moved: 49.9%
/dev/loop2: Moved: 100.0%
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 0
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop2 vgdata lvm2 -- 2.00g 2.00g
/dev/loop3 vgdata lvm2 a- 2.00g 0
</pre>
Then we remove ''/dev/loop2'' from the VG and we wipe its LVM metadata:
<pre>
# vgreduce vgdata /dev/loop2
Removed "/dev/loop2" from volume group "vgdata"
# pvremove /dev/loop2
Labels on physical volume "/dev/loop2" successfully wiped
</pre>
Final state of the PVs composing ''vgdata'':
<pre>
# pvs
PV VG Fmt Attr PSize PFree
/dev/loop0 vgdata lvm2 a- 2.00g 0
/dev/loop1 vgdata lvm2 a- 2.00g 1016.00m
/dev/loop3 vgdata lvm2 a- 2.00g 0
</pre>
''/dev/loop0'' took the place of ''/dev/loop2'' :-)
= More advanced topics =
== Backing up the layout ==
== Freezing a VG ==
== LVM snapshots ==
Screencasting is an easy method to explain complex tasks. Take for instance <code>youtu.be/5KDei5mBfSg</code> and chop off the id and insert it into the following syntax to produce a video example.
== Linear/Stripped/Mirrored Logical volumes ==
<pre>{{#widget:YouTube16x9|id=5KDei5mBfSg}}</pre>
{{#widget:YouTube16x9|id=5KDei5mBfSg}}
= LVM and Funtoo =
{{tip|The sample video above explains how to create your own screencasts under Funtoo Linux.}}
Most YouTube videos are in 16x9 format and should use the <code>YouTube16x9</code> widget. There is also a <code>YouTube4x3</code> widget for videos with a 4x3 aspect ratio.
{{note|These YouTube widgets have been updated to be mobile-friendly.}}
[[Category:Labs]]
[[Category:Wiki Development]]
[[Category:Filesystems]]
[[Category:Articles]]
{{ArticleFooter}}
Revision as of 07:38, January 4, 2015
Thanks for your interest in contributing to the the Funtoo wiki!
Types of Edits
Before we get started, let's review what changes are okay to make, and what changes are not okay:
Note that if you experience some problem with Funtoo Linux, during installation or otherwise, the proper course of action is to not add a work-around to our documentation, but to open a bug on our bug tracker. This is important because the problem you experienced may be a legitimate bug and the solution may be to fix the bug rather than add a work-around to our documentation. We may end up fixing a bug, making a documentation fix, or possibly both.
Basics
Here is a list of basic wiki information that you will need to know to get started:
You can create a new page by navigating to http://www.funtoo.org/New_Page_Name. Underscores are the equivalent of spaces. Then select "Create" under the "Actions" menu.
Whether creating a new page or editing an existing page by clicking "Edit", you will be presented with Web-based text editor that allows you to modify the wikitext of the page. The wikitext is rendered to produce the document you see when you view the page normally.
Another fun thing you can do is click on your name under the "Account" menu once you have logged in. This will bring you to your "User" page. Then click "Create with Form" unde the "Actions" menu and enter your geographic and other information. This will allow you to be displayed on our Usermap and will also allow your full name to be displayed on Ebuild pages for which you are an author. It's generally a good idea to do this.
Tip
The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.
Paragraphs
To create a new paragraph, insert a blank line between two lines of text. If a blank line doesn't exist between two lines of wikitext, they will be combined into a single flowing paragraph.
If you leave leading whitespace at the beginning of a line, MediaWiki will render it as pre-formatted text. Beware of this. Here's an example:
foobar
This can rear its ugly head when specifying template parameters, so you will get this:
Note
ugh!
...instead of this:
Note
This looks much better!
Page and Section Capitalization
In general, capitalize all words in page names and section heading except:
Articles: a, an, the
Coordinating Conjunctions: and, but, or, for, nor, etc.
Prepositions (fewer than five letters): on, at, to, from, by, etc.
Document Hierarchy
Use section headings to create a document hierarchy for your page. These will define the table of contents that appears at the top of the wiki page. Create chapters, sections and sub-sections as follows:
= Page Title =
== Chapter Title ==
=== Section Title ===
==== SubSection Title ====
Note
By default, Table of Contents is disabled on the Funtoo wiki. If you would like to enable the TOC, you can place a __TOC__ on a blank line where you'd like the Table of Contents to appear, or place __FORCETOC__ on a blank line anywhere in the wikitext to force the TOC to appear at the top of the page.
In general, when creating new documents, it's best to use level-3 (three "="'s) Section Titles to break up content. Level-2 Section Titles are best used for major sections of larger documents. Use them infrequently. Level-1 Section Titles generally do not need to be used.
Links
Internal links to other wiki pages can be specified as [[pagename]]. To specify an alternate name for the link, use [[pagename|my link name]].
For external links, use [http://funtoo.org my link] to specify a URL. If you want the URL to appear in the wikitext, you can specify it without brackets: http://forums.funtoo.org.
Lists
MediaWiki supports a number of list formats:
Unordered List
Unordered Item 2
Unordered sub-item
Ordered List
Ordered Item 2
Ordered sub-item
Term
This is called a "definition list". It is used when defining various terms.
If you need to quote a portion of text from another site, use <blockquote> as follows:
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, the largest with 1.2 billion unique visitors."[10]
Literal Text and HTML Symbols
Here is wikitext for the section above, which I am displaying by placing the literal wikitext between a <pre> and </pre> tag. If you want to disable wikitext processing for an inline span of text, use <nowiki> and </nowiki>. If you want to print out a tag literally, use < and > (In the wikitext, I used &#60; and &#62 to display these!)
* Unordered List
* Unordered Item 2
** Unordered sub-item
# Ordered List
# Ordered Item 2
## Ordered sub-item
;Term: This is called a "definition list". It is used when defining various terms.
If you need to quote a portion of text from another site, use <tt><blockquote></tt> as follows:
<blockquote>
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access,
free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers
worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the
English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet
comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York
Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views
and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google,
the largest with 1.2 billion unique visitors."[10]
</blockquote>
Linking to Packages
To link to a package page, use the Package template:
{{Package|sys-apps/portage}}
This template will create a link to the official wiki page for sys-apps/portage, and render using the official "English" page name, as follows:
This table syntax has an added benefit of creating a responsive table that renders properly on mobile devices.
It is possible to use the following CSS classes with tr (rows) and td/th elements to color them as desired:
Class Name
success
info
warning
active
danger
Displaying Source Code
To display source code, use can use the file template, specifying a lang= parameter:
{{file|name=foobar|lang=python|desc=foobarosity|body=
import system
}}
This will produce:
foobar (python source code) - foobarosity
importsystem
The parameters name (filename), lang (language for syntax highlighting) and desc (Description, appearing as a caption) are optional. For a list of supported languages, see this list.
Important
If you need to display the pipe ("|") character within the body of a file template, replace each "|" with {{!}} -- otherwise your file contents will not display properly. This is necessary because {{file}} is a template and the "|" character is used as a delimiter for arguments to the template.
Displaying Text File Contents
For displaying the contents of non-programming language text files (like config files), you have two options. You can enclose your lines within <pre> tags, or use the new file template. The file template is used like so:
Note that we use a # prompt for root and a $ prompt to denote a non-root user.
Important
The ##i## text tags the rest of the line as being user input ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.
If you need to end highlighting of user input prior to the end of a line, use ##!i## to mark the end of the highlighted area.
The following special character sequences are also available:
##g## - Green
##y## - Yellow
##bl## - Blue
##r## - Red
##b## - Bold
Please use the above coloring options sparingly. It is sometimes nice to use them to get wiki console output to match the colors that are displayed on a Linux console. Also note that for every color above, there is a matching ##!(colorcode)## option to turn color off prior to end of line.
Here is an example of its use:
root#bluetoothctl
[NEW] Controller 00:02:72:C9:62:65 antec [default]
root##bl##[bluetooth]##!bl###power on
Changing power on succeeded
root##bl##[bluetooth]##!bl### agent on
Agent registered
root##bl##[bluetooth]##!bl### scan on
Discovery started
root##bl##[bluetooth]##!bl### devices
Device 00:1F:20:3D:1E:75 Logitech K760
root##bl##[bluetooth]##!bl### pair 00:1F:20:3D:1E:75
Attempting to pair with 00:1F:20:3D:1E:75
[CHG] Device 00:1F:20:3D:1E:75 Connected: yes
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
root##r##[agent]##!r## Passkey: 454358
[CHG] Device 00:1F:20:3D:1E:75 Paired: yes
Pairing successful
[CHG] Device 00:1F:20:3D:1E:75 Connected: no
root##bl##[bluetooth]##!bl### connect 00:1F:20:3D:1E:75
Attempting to connect to 00:1F:20:3D:1E:75
[CHG] Device 00:1F:20:3D:1E:75 Connected: yes
Connection successful
root##bl##[bluetooth]##!bl### quit
[DEL] Controller 00:02:72:C9:62:65 antec [default]
root#
Informational Messages
Notes, warnings, tips, and important templates can be used for informational messages that need to be offset from the regular text flow:
{{note|this is a note}}
Note
this is a note
{{important|this is important}}
Important
this is important
{{warning|this is a warning}}
Warning
this is a warning
{{tip|this is a tip}}
Tip
this is a tip
Note that these templates used to be called fancynote, fancytip, etc. The "fancy" names have been deprecated but will still be supported for the forseeable future.
Kernelop
To display kernel configuration options, we encourage you to use the kernelop template. To use the kernelop template, create an entry similar to the following example:
{{kernelop|title=foo,bar|desc=
kernel options pasted from "make menuconfig"
}}
Note
Kernelop is colored blue to slightly resemble the blueish background from make menuconfig.
Adding this entry will give you the following output:
Under foo-->bar:
kernel options
Here's a more concrete example:
Under File systems:
<M> Second extended fs support
[ ] Ext2 extended attributes
[ ] Ext2 execute in place support
<M> Ext3 journalling file system support
In MediaWiki, every "regular" wiki page has a corresponding "Talk" or "Discussion" page which has a page name prefixed by "Talk:" -- you can get to this page by going to the "Action" menu, and then choosing the "Discussion" menu item. These talk pages are typically used to discuss the edits that are going on in the "main" wiki page. The problem with talk pages is that they are kind of a pain to use. However, we have a way to fix that. If you want to enable a DISQUS-based mini-forum on a talk page, insert the following wikitext on the Talk page:
{{DISQUS}}
...and presto! You will now have DISQUS-powered mini-forums to discuss whatever you want about your wiki page.
Marking Pages as Needing Updates
If you find outdated wiki content, but you don't have the time or ability to update it, add one of the following templates to the wikitext of the page. This will add the page to the Needs Updates Category so we can identify pages that need updating:
To emphasize commands, and other technical jargon when they appear inline in a paragraph, use the {{c}} template. When referencing files, use the {{f}} template.
The {{f|/etc/fstab}} file is an important one. Another important file is {{f|/boot/grub/grub.cfg}}. The {{c|emerge}} command is really nifty.
This example produces the following output:
The /etc/fstab file is an important one. Another important file is /boot/grub/grub.cfg. The emerge command is really nifty.
Important
The <tt> tag has been deprecated for the purpose of tagging inline code, to conform with HTML5, and the previous use of the <code> tag is discouraged. It is more maintainable to use the {{c}} template.
Slideshow
Any page has the capability of displaying a slideshow. Adding a slideshow to a page involves three steps:
Upload Images
Define Slides
Add Slideshow to page
Upload Images
To upload images, head to Special:Upload and upload a file. It is highly recommended to upload JPEG format images in high resolution -- MediaWiki will handle scaling JPEG automatically, saving bandwidth, but does not do this for PNG. Make sure that all images you upload have the same dimensions. When you upload, make note of the Destination Filename field -- this is the name that the upload will use when you reference it in your slide. It is recommended that you choose a simple descriptive name ending in ".jpg" for the Destination Filename.
Define Slides
Once images have been uploaded, you must define slides. To define slides on a page, you enter special semantic information about the slide on the page that it will be displayed, in the following format:
{{#subobject:|slideIndex=0|slideCaption=
== Wikitext Here ==
This is a fantastic slide!
|slideImage=File:Fruit.jpg|slideLink=PageName}}
Here are some important instructions regarding defining slides:
slideIndex must be 0 for the first slide, 1 for the second slide, etc. Numbers must be unique and incrementing from zero, and not doing this will result in slideshow display errors (but can be easily fixed by correcting the wikitext.)
slideCaption= can contain wikitext, such as headings and links. The best way to enter slideCaption is as above -- type a literal slideCaption=, followed by enter, then specify your wikitext, and terminate the caption by a single pipe character on the following line. Pipe characters are used to separate arguments from each other.
Specify your image name in the slideImage field. Your slideImage will have a name of File:myname.jpg, where myname.jpg is the Destination Filename you used when uploading the image.
An optional parameter called slideLink= can be provided to allow the image to be clickable and link to another wiki page. If it is omitted, then the image will not be clickable.
Add Slideshow to Page
Once the slides have been added to the page, you can add the following text to your page at the point you'd like the slideshow to appear:
{{Slideshow}}
YouTube Videos (Screencasts, etc.)
Screencasting is an easy method to explain complex tasks. Take for instance youtu.be/5KDei5mBfSg and chop off the id and insert it into the following syntax to produce a video example.
{{#widget:YouTube16x9|id=5KDei5mBfSg}}
Tip
The sample video above explains how to create your own screencasts under Funtoo Linux.
Most YouTube videos are in 16x9 format and should use the YouTube16x9 widget. There is also a YouTube4x3 widget for videos with a 4x3 aspect ratio.
Note
These YouTube widgets have been updated to be mobile-friendly.