Difference between pages "Linux Fundamentals, Part 3" and "Forking An Ebuild"

(Difference between pages)
 
m
 
Line 1: Line 1:
{{Article
+
Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.
|Author=Drobbins
+
|Previous in Series=Linux Fundamentals, Part 2
+
|Next in Series=Linux Fundamentals, Part 4
+
}}
+
== Before You Start ==
+
  
=== About this tutorial ===
+
== Portage Tree Generation ==
Welcome to "Intermediate administration," the third of four tutorials designed to prepare you for the Linux Professional Institute's 101 (release 2) exam. This tutorial (Part 3) is ideal for those who want to improve their knowledge of fundamental Linux administration skills. We'll cover a variety of topics, including system and Internet documentation, the Linux permissions model, user account management, and login environment tuning.
+
  
If you are new to Linux, we recommend that you start with [[Linux Fundamentals, Part 1|Part 1]] and [[Linux Fundamentals, Part 2|Part 2]]. For some, much of this material will be new, but more experienced Linux users may find this tutorial to be a great way of "rounding out" their foundational Linux system administration skills.
+
Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our [https://github.com/funtoo/funtoo-overlay Funtoo-overlay]. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.  
  
By the end of this series of tutorials (eight in all covering the LPI 101 and 102 exams), you will have the knowledge you need to become a Linux Systems Administrator and will be ready to attain an LPIC Level 1 certification from the Linux Professional Institute if you so choose.
+
In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the <tt>sys-foo/bar</tt> directory in one of our overlays.
  
== System and network documentation ==
+
If you're interested in seeing the actual script that does all these things, take a look at the following files:
  
=== Types of Linux system documentation ===
+
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh: cronned script that calls <tt>merge.py</tt>.
There are essentially three sources of documentation on a Linux system: manual pages, info pages, and application-bundled documentation in '''/usr/share/doc'''. In this section, we'll explore each of these sources before looking "outside the box" for more information.
+
;http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py: python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
 +
; http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py: python module that contains classes and methods that implement the merging functionality.
  
=== Manual pages ===
+
== Forking an Ebuild ==
Manual pages, or "man pages", are the classic form of UNIX and Linux reference documentation. Ideally, you can look up the man page for any command, configuration file, or library routine. In practice, Linux is free software, and some pages haven't been written or are showing their age. Nonetheless, man pages are the first place to look when you need help.
+
  
To access a man page, simply type <span style="color:green">man</span> followed by your topic of inquiry. A pager will be started, so you will need to press <span style="color:green">q</span> when you're done reading. For example, to look up information about the <span style="color:green">ls</span> command, you would type:
+
In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to <tt>sys-foo/bar</tt>, you are going to fork all <tt>sys-foo/bar</tt> ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork <tt>sys-foo/bar</tt>:
<pre>
+
$ man ls
+
</pre>
+
Knowing the layout of a man page can be helpful to jump quickly to the information you need. In general, you will find the following sections in a <span style="color:green">man</span> page:
+
{| {{table}}
+
|-
+
|NAME
+
|Name and one-line description of the command
+
|-
+
|SYNOPSIS
+
|How to use the command
+
|-
+
|DESCRIPTION
+
|In-depth discussion on the functionality of the command
+
|-
+
|EXAMPLES
+
|Suggestions for how to use the command
+
|-
+
|SEE ALSO
+
|Related topics (usually man pages)
+
|}
+
  
=== man page sections ===
+
# Find <tt>sys-foo/bar</tt> in you regular Portage tree. Make sure you have run <tt>emerge --sync</tt> recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for <tt>sys-foo/bar</tt> (this typically isn't necessary.)
The files that comprise manual pages are stored in '''/usr/share/man''' (or in '''/usr/man''' on some older systems). Inside that directory, you will find that the manual pages are organized into the following sections:
+
<console>
{| {{table}}
+
# alias to recursively grab latest from Gentoo Portage tree WITHOUT history
|-
+
# usage: getgen gentoo-x86/dev-db/mongodb
|man1
+
alias getgen="cvs -d :pserver:anonymous@anoncvs.gentoo.org:/var/cvsroot export -D$(date '+%Y-%m-%d')"
|User programs
+
</console>
|-
+
# Copy the <tt>sys-foo/bar</tt> directory in its entirety to <tt>funtoo-overlay/sys-foo/bar</tt>.
|man2
+
# Make any necessary modifications to <tt>funtoo-overlay/sys-foo/bar</tt>.
|System calls
+
# Perform some funtoo-ification steps prior to commit.
|-
+
# Add and commit the changes to funtoo-overlay.
|man3
+
# Push changes to funtoo-overlay.
|Library functions
+
|-
+
|man4
+
|Special files
+
|-
+
|man5
+
|File formats
+
|-
+
|man6
+
|Games
+
|-
+
|man7
+
|Miscellaneous
+
|}
+
  
=== Multiple man pages ===
+
At this point, the forked <tt>sys-foo/bar</tt> package will be part of funtoo-overlay. The next time our unified Portage tree is generated by <tt>merge.py</tt> (the one that users have in their <tt>/usr/portage</tt> and is updated via <tt>emerge --sync</tt>), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our <tt>merge.py</tt> script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our <tt>sys-foo/bar</tt> directory will be used in place of Gentoo's <tt>sys-foo/bar</tt> directory. So this is how the forking process works.
Some topics exist in more than one section. To demonstrate this, let's use the <span style="color:green">whatis</span> command, which shows all the available man pages for a topic:
+
<pre>
+
$ whatis printf
+
printf              (1)  - format and print data
+
printf              (3)  - formatted output conversion
+
</pre>
+
In this case, <span style="color:green">man printf</span> would default to the page in section 1 ("User Programs"). If we were writing a C program, we might be more interested in the page from section 3 ("Library functions"). You can call up a man page from a certain section by specifying it on the command line, so to ask for printf(3), we would type:
+
<pre>
+
$ man 3 printf
+
</pre>
+
  
=== Finding the right man page ===
+
== Funtoo-ification ==
Sometimes it's hard to find the right man page for a given topic. In that case, you might try using <span style="color:green">man -k</span> to search the NAME section of the man pages. Be warned that it's a substring search, so running something like <span style="color:green">man -k ls</span> will give you a lot of output! Here's an example using a more specific query:
+
<pre>
+
$ man -k whatis
+
apropos              (1)  - search the whatis database for strings
+
makewhatis          (8)  - Create the whatis database
+
whatis              (1)  - search the whatis database for complete words
+
</pre>
+
  
=== All about apropos ===
+
When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:
The example on the previous panel brings up a few more points. First, the <span style="color:green">apropos</span> command is exactly equivalent to <span style="color:green">man -k</span>. (In fact, I'll let you in on a little secret. When you run <span style="color:green">man -k</span>, it actually runs <span style="color:green">apropos</span> behind the scenes.) The second point is the <span style="color:green">makewhatis</span> command, which scans all the man pages on your Linux system and builds the database for <span style="color:green">whatis</span> and <span style="color:green">apropos</span>. Usually this is run periodically by root to keep the database updated:
+
<pre>
+
# makewhatis
+
</pre>
+
For more information on "man" and friends, you should start with its man page:
+
<pre>
+
$ man man
+
</pre>
+
  
=== The MANPATH ===
+
# Removal of <tt>ChangeLog</tt>.
By default, the <span style="color:green">man</span> program will look for man pages in '''/usr/share/man''', '''/usr/local/man''', '''/usr/X11R6/man''', and possibly '''/opt/man'''. Sometimes, you may find that you need to add an additional item to this search path. If so, simply edit '''/etc/man.conf''' in a text editor and add a line that looks like this:
+
# Run <tt>ebuild foo-1.0.ebuild digest</tt> before committing. This will cause the <tt>Manifest</tt> file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called <tt>Manifest</tt>, just with less entries in it) rather than the one that came from Gentoo.
<pre>
+
# Edit the top of each ebuild, and remove all <tt>Copyright</tt> and <tt>$Header:</tt> lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the <tt>$Header:</tt> line is there for the CVS version control system in Gentoo which Funtoo does not use. ''The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2.''.
MANPATH /opt/man
+
</pre>
+
From that point forward, any man pages in the '''/opt/man/man*''' directories will be found. Remember that you'll need to rerun <span style="color:green">makewhatis</span> to add these new man pages to the whatis database.
+
  
=== GNU info ===
+
<console>
One shortcoming of man pages is that they don't support hypertext, so you can't jump easily from one to another. The GNU folks recognized this shortcoming, so they invented another documentation format: "info" pages. Many of the GNU programs come with extensive documentation in the form of info pages. You can start reading info pages with the <span style="color:green">info</span> command:
+
# If you find yourself doing this often, place this function in your .bashrc, .zshrc, etc
<pre>
+
funtooize() {
$ info
+
    if [ -z "$1" ]; then
</pre>
+
        search_path='.'
Calling <span style="color:green">info</span> in this way will bring up an index of the available pages on the system. You can move around with the arrow keys, follow links (indicated with a star) using the Enter key, and quit by pressing <span style="color:green">q</span>. The keys are based on Emacs, so you should be able to navigate easily if you're familiar with that editor. For an intro to the Emacs editor, see the developerWorks tutorial, [http://www-106.ibm.com/developerworks/edu/l-dw-linuxemacs-i.html Living in Emacs].
+
    else
 +
        search_path=$1
 +
    fi
  
You can also specify an info page on the command line:
+
    find $search_path -type f -exec sed -i -e '/^# Copyright\|^# \$Header/d' {} +
<pre>
+
    find $search_path -type f -name "ChangeLog*" -delete
$ info diff
+
    find $search_path -type f -name '*.ebuild' -exec ebuild {} manifest \;
</pre>
+
}
For more information on using the info reader, try reading its info page. You should be able to navigate primitively using the few keys I've already mentioned:
+
</console>
<pre>
+
$ info info
+
</pre>
+
  
=== /usr/share/doc ===
+
Here are a few additional changes that you are allowed to make to any forked ebuilds:
There is a final source for help within your Linux system. Many programs are shipped with additional documentation in other formats: text, PDF, PostScript, HTML, to name a few. Take a look in '''usr/share/doc''' (or '''/usr/doc''' on older systems). You'll find a long list of directories, each of which came with a certain application on your system. Searching through this documentation can often reveal some gems that aren't available as man pages or info pages, such as tutorials or additional technical documentation. A quick check reveals there's a lot of reading material available:
+
<pre>
+
$ cd /usr/share/doc
+
$ find . -type f | wc -l
+
7582
+
</pre>
+
Whew! Your homework this evening is to read just half (3791) of those documents. Expect a quiz tomorrow. ;-)
+
  
=== The Linux Documentation Project ===
+
# Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
In addition to system documentation, there are a number of excellent Linux resources on the Internet. The [http://www.tldp.org/ Linux Documentation Project] is a group of volunteers who are working on putting together the complete set of free Linux documentation. This project exists to consolidate various pieces of Linux documentation into a location that is easy to search and use.
+
# <tt>KEYWORDS</tt> of <tt>*</tt> and <tt>~*</tt>. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
 +
# Use of <tt>4-python</tt> EAPI. We allow the use of this EAPI for enhanced python functionality.
  
=== An LDP overview ===
+
[[Category:Development]]
The LDP is made up of the following areas:
+
 
+
* Guides - longer, more in-depth books, such as [http://www.tldp.org/LDP/lpg/index.html The Linux Programmer's Guide]
+
* HOWTOs - subject-specific help, such as the [http://www.tldp.org/HOWTO/DSL-HOWTO/index.html DSL HOWTO]
+
* FAQs - Frequently Asked Questions with answers, such as the [http://www.tldp.org/FAQ/faqs/BLFAQ Brief Linux FAQ]
+
* Man pages - help on individual commands (these are the same manual pages you get on your Linux system when you use the man command).
+
 
+
If you aren't sure which section to peruse, you can take advantage of the search box, which allows you to find things by topic.
+
 
+
The LDP additionally provides a list of Links and Resources such as [http://www.tldp.org/LDP/LG/current/ Linux Gazette] (see links in [[#Resources|Resources]]) and [http://www.lwn.net/ Linux Weekly News], as well links to mailing lists and news archives.
+
 
+
=== Mailing lists ===
+
Mailing lists provide probably the most important point of collaboration for Linux developers. Often projects are developed by contributors who live far apart, possibly even on opposite sides of the globe. Mailing lists provide a method for each developer on a project to contact all the others, and to hold group discussions via e-mail. One of the most famous development mailing lists is the [http://www.tux.org/lkml/ Linux Kernel Mailing List].
+
 
+
=== More about mailing lists ===
+
In addition to development, mailing lists can provide a method for asking questions and receiving answers from knowledgeable developers, or even other users. For example, individual distributions often provide mailing lists for newcomers. You can check your distribution's Web site for information on the mailing lists it provides.
+
 
+
If you took the time to read the LKML FAQ at the link on the previous panel, you might have noticed that mailing list subscribers often don't take kindly to questions being asked repeatedly. It's always wise to search the archives for a given mailing list before writing your question. Chances are, it will save you time, too!
+
 
+
=== Newsgroups ===
+
Internet "newsgroups" are similar to mailing lists, but are based on a protocol called NNTP ("Network News Transfer Protocol") instead of e-mail. To participate, you need to use an NNTP client such as <span style="color:green">slrn</span> or <span style="color:green">pan</span>. The primary advantage is that you only take part in the discussion when you want, instead of having it continually arrive in your inbox. :-)
+
 
+
The newsgroups of primary interest start with comp.os.linux. You can browse the list on the [http://www.tldp.org/links/#ng LDP] site.
+
 
+
=== Vendor and third-party Web sites ===
+
Web sites for the various Linux distributions often provide updated documentation, installation instructions, hardware compatibility/incompatibility statements, and other support such as a knowledge base search tool. For example:
+
 
+
* [http://www.redhat.com/ Redhat Linux]
+
* [http://www.debian.org/ Debian Linux]
+
* [http://www.gentoo.org/ Gentoo Linux]
+
* [http://www.suse.com/ SuSE Linux]
+
* [http://www.caldera.com/ Caldera]
+
* [http://www.turbolinux.com/ Turbolinux]
+
 
+
=== Hardware and software vendors ===
+
Many hardware and software vendors have added Linux support to their products in recent years. At their sites, you can find information about which hardware supports Linux, software development tools, released sources, downloads of Linux drivers for specific hardware, and other special Linux projects. For example:
+
 
+
* [http://www.ibm.com/linux/ IBM and Linux]
+
* [http://www.hp.com/products1/linux/ HP and Linux]
+
* [http://www.sun.com/linux/ Sun and Linux]
+
* [http://technet.oracle.com/tech/linux/content.html Oracle and Linux].
+
 
+
== The Linux permissions model ==
+
 
+
=== One user, one group ===
+
In this section, we'll take a look at the Linux permissions and ownership model. We've already seen that every file is owned by one user and one group. This is the very core of the permissions model in Linux. You can view the user and group of a file in a ls -l listing:
+
<pre>
+
$ ls -l /bin/bash
+
-rwxr-xr-x    1 root    wheel      430540 Dec 23 18:27 /bin/bash
+
</pre>
+
In this particular example, the '''/bin/bash''' executable is owned by root and is in the wheel group. The Linux permissions model works by allowing three independent levels of permission to be set for each filesystem object -- those for the file's owner, the file's group, and all other users.
+
 
+
=== Understanding "ls -l" ===
+
Let's take a look at our <span style="color:green">ls -l</span> output and inspect the first column of the listing:
+
<pre>
+
$ ls -l /bin/bash
+
-rwxr-xr-x    1 root    wheel      430540 Dec 23 18:27 /bin/bash
+
</pre>
+
This first field -rwxr-xr- contains a symbolic representation of this particular files' permissions. The first character (-) in this field specifies the type of this file, which in this case is a regular file. Other possible first characters:
+
{| {{table}}
+
|-
+
|'d'
+
|directory
+
|-
+
|'l'
+
|symbolic link
+
|-
+
|'c'
+
|character special device
+
|-
+
|'b'
+
|block special device
+
|-
+
|'p'
+
|fifo
+
|-
+
|'s'
+
|socket
+
|}
+
 
+
=== Three triplets ===
+
<pre>
+
$ ls -l /bin/bash
+
-rwxr-xr-x    1 root    wheel      430540 Dec 23 18:27 /bin/bash
+
</pre>
+
The rest of the field consists of three character triplets. The first triplet represents permissions for the owner of the file, the second represents permissions for the file's group, and the third represents permissions for all other users:
+
<pre>
+
"rwx"
+
"r-x"
+
"r-x"
+
</pre>
+
Above, the r means that reading (looking at the data in the file) is allowed, the w means that writing (modifying the file, as well as deletion) is allowed, and the x means that "execute" (running the program) is allowed. Putting together all this information, we can see that everyone is able to read the contents of and execute this file, but only the owner (root) is allowed to modify this file in any way. So, while normal users can copy this file, only root is allowed to update it or delete it.
+
 
+
=== Who am I? ===
+
Before we take a look at how to change the user and group ownership of a file, let's first take a look at how to learn your current user id and group membership. Unless you've used the su command recently, your current user id is the one you used to log in to the system. If you use su frequently, however, you may not remember your current effective user id. To view it, type <span style="color:green">whoami</span>:
+
<pre>
+
# whoami
+
root
+
# su drobbins
+
$ whoami
+
drobbins
+
</pre>
+
 
+
=== What groups am I in? ===
+
To see what groups you belong to, use the <span style="color:green">groups</span> command:
+
<pre>
+
$ groups
+
drobbins wheel audio
+
</pre>
+
In the above example, I'm a member of the drobbins, wheel, and audio groups. If you want to see what groups other user(s) are in, specify their usernames as arguments:
+
<pre>
+
$ groups root daemon
+
root : root bin daemon sys adm disk wheel floppy dialout tape video
+
daemon : daemon bin adm
+
</pre>
+
 
+
=== Changing user and group ownership ===
+
To change the owner or group of a file or other filesystem object, use <span style="color:green">chown</span> or <span style="color:green">chgrp</span>, respectively. Each of these commands takes a name followed by one or more filenames.
+
<pre>
+
# chown root /etc/passwd
+
# chgrp wheel /etc/passwd
+
</pre>
+
You can also set the owner and group simultaneously with an alternate form of the <span style="color:green">chown</span> command:
+
<pre>
+
# chown root:wheel /etc/passwd
+
</pre>
+
You may not use <span style="color:green">chown</span> unless you are the superuser, but <span style="color:green">chgrp</span> can be used by anyone to change the group ownership of a file to a group to which they belong.
+
 
+
=== Recursive ownership changes ===
+
Both <span style="color:green">chown</span> and <span style="color:green">chgrp</span> have a -R option that can be used to tell them to recursively apply ownership and group changes to an entire directory tree. For example:
+
<pre>
+
# chown -R drobbins /home/drobbins
+
</pre>
+
 
+
=== Introducing chmod ===
+
<span style="color:green">chown</span> and <span style="color:green">chgrp</span> can be used to change the owner and group of a filesystem object, but another program, called <span style="color:green">chmod</span>, is used to change the rwx permissions that we can see in an <span style="color:green">ls -l</span> listing. <span style="color:green">chmod</span> takes two or more arguments: a "mode", describing how the permissions should be changed, followed by a file or list of files that should be affected:
+
<pre>
+
$ chmod +x scriptfile.sh
+
</pre>
+
In the above example, our "mode" is +x. As you might guess, a +x mode tells <span style="color:green">chmod</span> to make this particular file executable for both the user and group and for anyone else.
+
 
+
If we wanted to remove all execute permissions of a file, we'd do this:
+
<pre>
+
$ chmod -x scriptfile.sh
+
</pre>
+
 
+
=== User/group/other granularity ===
+
So far, our <span style="color:green">chmod</span> examples have affected permissions for all three triplets -- the user, the group, and all others. Often, it's handy to modify only one or two triplets at a time. To do this, simply specify the symbolic character for the particular triplets you'd like to modify before the + or - sign. Use u for the "user" triplet, g for the "group" triplet, and o for the "other/everyone" triplet:
+
<pre>
+
$ chmod go-w scriptfile.sh
+
</pre>
+
We just removed write permissions for the group and all other users, but left "owner" permissions untouched.
+
 
+
=== Resetting permissions ===
+
In addition to flipping permission bits on and off, we can also reset them altogether. By using the = operator, we can tell <span style="color:green">chmod</span> that we want the specified permissions and no others:
+
<pre>
+
$ chmod =rx scriptfile.sh
+
</pre>
+
Above, we just set all "read" and "execute" bits, and unset all "write" bits. If you just want to reset a particular triplet, you can specify the symbolic name for the triplet before the = as follows:
+
<pre>
+
$ chmod u=rx scriptfile.sh
+
</pre>
+
 
+
=== Numeric modes ===
+
Up until now, we've used what are called symbolic modes to specify permission changes to <span style="color:green">chmod</span>. However, there's another common way of specifying permissions: using a 4-digit octal number. Using this syntax, called numeric permissions syntax, each digit represents a permissions triplet. For example, in 1777, the 777 sets the "owner", "group", and "other" flags that we've been discussing in this section. The 1 is used to set the special permissions bits, which we'll cover later (see " The elusive first digit" at the end of this section). This chart shows how the second through fourth digits (777) are interpreted:
+
{| {{table}}
+
!Mode
+
!Digit
+
|-
+
|rwx
+
|7
+
|-
+
|rw&minus;
+
|6
+
|-
+
|r&minus;x
+
|5
+
|-
+
|r&minus;&minus;
+
|4
+
|-
+
|&minus;wx
+
|3
+
|-
+
|&minus;w&minus;
+
|2
+
|-
+
|&minus;&minus;x
+
|1
+
|-
+
|&minus;&minus;&minus;
+
|0
+
|}
+
 
+
=== Numeric permission syntax ===
+
Numeric permission syntax is especially useful when you need to specify all permissions for a file, such as in the following example:
+
<pre>
+
$ chmod 0755 scriptfile.sh
+
$ ls -l scriptfile.sh
+
-rwxr-xr-x    1 drobbins drobbins        0 Jan  9 17:44 scriptfile.sh
+
</pre>
+
In this example, we used a mode of 0755, which expands to a complete permissions setting of -rwxr-xr-x.
+
 
+
=== The umask ===
+
When a process creates a new file, it specifies the permissions that it would like the new file to have. Often, the mode requested is 0666 (readable and writable by everyone), which is more permissive that we would like. Fortunately, Linux consults something called a "umask" whenever a new file is created. The system uses the umask value to reduce the originally specified permissions to something more reasonable and secure. You can view your current umask setting by typing umask at the command line:
+
<pre>
+
$ umask
+
0022
+
</pre>
+
On Linux systems, the umask normally defaults to 0022, which allows others to read your new files (if they can get to them) but not modify them.
+
 
+
To make new files more secure by default, you can change the umask setting:
+
<pre>
+
$ umask 0077
+
</pre>
+
This umask will make sure that the group and others will have absolutely no permissions for any newly created files. So, how does the umask work? Unlike "regular" permissions on files, the umask specifies which permissions should be turned off. Let's consult our mode-to-digit mapping table so that we can understand what a umask of 0077 means:
+
{| {{table}}
+
!Mode
+
!Digit
+
|-
+
|rwx
+
|7
+
|-
+
|rw&minus;
+
|6
+
|-
+
|r&minus;x
+
|5
+
|-
+
|r&minus;&minus;
+
|4
+
|-
+
|&minus;wx
+
|3
+
|-
+
|&minus;w&minus;
+
|2
+
|-
+
|&minus;&minus;x
+
|1
+
|-
+
|&minus;&minus;&minus;
+
|0
+
|}
+
 
+
Using our table, the last three digits of 0077 expand to ---rwxrwx. Now, remember that the <span style="color:green">umask</span> tells the system which permissions to disable. Putting two and two together, we can see that all "group" and "other" permissions will be turned off, while "user" permissions will remain untouched.
+
 
+
=== Introducing suid and sgid ===
+
When you initially log in, a new shell process is started. You already know that, but you may not know that this new shell process (typically bash) runs using your user id. As such, the bash program can access all files and directories that you own. In fact, we as users are totally dependent on other programs to perform operations on our behalf. Because the programs you start inherit your user id, they cannot access any filesystem objects for which you haven't been granted access.
+
 
+
For example, the passwd file cannot be changed by normal users directly, because the "write" flag is off for every user except root:
+
<pre>
+
$ ls -l /etc/passwd
+
-rw-r--r--    1 root    wheel        1355 Nov  1 21:16 /etc/passwd
+
</pre>
+
However, normal users do need to be able to modify /etc/passwd (at least indirectly) whenever they need to change their password. But, if the user is unable to modify this file, how exactly does this work?
+
 
+
=== suid ===
+
Thankfully, the Linux permissions model has two special bits called <span style="color:green">suid</span> and <span style="color:green">sgid</span>. When an executable program has the <span style="color:green">suid</span> bit set, it will run on behalf of the owner of the executable, rather than on behalf of the person who started the program.
+
 
+
Now, back to the '''/etc/passwd problem'''. If we take a look at the <span style="color:green">passwd</span> executable, we can see that it's owned by root:
+
<pre>
+
$ ls -l /usr/bin/passwd
+
-rwsr-xr-x    1 root    wheel      17588 Sep 24 00:53 /usr/bin/passwd
+
</pre>
+
You'll also note that in place of an x in the user's permission triplet, there's an s. This indicates that, for this particular program, the <span style="color:green">suid</span> and executable bits are set. Because of this, when <span style="color:green">passwd</span> runs, it will execute on behalf of the root user (with full superuser access) rather than that of the user who ran it. And because <span style="color:green">passwd</span> runs with root access, it's able to modify the '''/etc/passwd''' file with no problem.
+
 
+
=== suid/sgid caveats ===
+
We've seen how <span style="color:green">suid</span> works, and <span style="color:green">sgid</span> works in a similar way. It allows programs to inherit the group ownership of the program rather than that of the current user.
+
 
+
{{fancyimportant|Here's some miscellaneous yet important information about suid and sgid. First, suid and sgid bits occupy the same space as the x bits in a ls -l listing. If the x bit is also set, the respective bits will show up as s (lowercase). However, if the x bit is not set, it will show up as a S (uppercase).}}
+
 
+
{{fancyimportant|Another important note: suid and sgid come in handy in many circumstances, but improper use of these bits can allow the security of a system to be breached. It's best to have as few suid programs as possible. The passwd command is one of the few that must be suid.}}
+
 
+
=== Changing suid and sgid ===
+
Setting and removing the <span style="color:green">suid</span> and <span style="color:green">sgid</span> bits is fairly straightforward. Here, we set the suid bit:
+
<pre>
+
# chmod u+s /usr/bin/myapp
+
</pre>
+
And here, we remove the <span style="color:green">sgid</span> bit from a directory. We'll see how the <span style="color:green">sgid</span> bit affects directories in just a few panels:
+
<pre>
+
# chmod g-s /home/drobbins
+
</pre>
+
 
+
=== Permissions and directories ===
+
So far, we've been looking at permissions from the perspective of regular files. When it comes to directories, things are a bit different. Directories use the same permissions flags, but they are interpreted to mean slightly different things.
+
 
+
For a directory, if the "read" flag is set, you may list the contents of the directory; "write" means you may create files in the directory; and "execute" means you may enter the directory and access any sub-directories inside. Without the "execute" flag, the filesystem objects inside a directory aren't accessible. Without a "read" flag, the filesystem objects inside a directory aren't viewable, but objects inside the directory can still be accessed as long as someone knows the full path to the object on disk.
+
 
+
=== Directories and sgid ===
+
And, if a directory has the "sgid" flag enabled, any filesystem objects created inside it will inherit the group of the directory. This particular feature comes in handy when you need to create a directory tree to be used by a group of people that all belong to the same group. Simply do this:
+
<pre>
+
# mkdir /home/groupspace
+
# chgrp mygroup /home/groupspace
+
# chmod g+s /home/groupspace
+
</pre>
+
Now, any users in the group mygroup can create files or directories inside '''/home/groupspace''', and they will be automatically assigned a group ownership of mygroup as well. Depending on the users' umask setting, new filesystem objects may or may not be readable, writable, or executable by other members of the mygroup group.
+
 
+
=== Directories and deletion ===
+
By default, Linux directories behave in a way that may not be ideal in all situations. Normally, anyone can rename or delete a file inside a directory, as long as they have write access to that directory. For directories used by individual users, this behavior is usually just fine.
+
 
+
However, for directories that are used by many users, especially '''/tmp''' and '''/var/tmp''', this behavior can be bad news. Since anyone can write to these directories, anyone can delete or rename anyone else's files -- even if they don't own them! Obviously, it's hard to use '''/tmp''' for anything meaningful when any other user can type <span style="color:green">rm -rf /tmp/*</span> at any time and destroy everyone's files.
+
 
+
Thankfully, Linux has something called the sticky bit. When '''/tmp''' has the sticky bit set (with a <span style="color:green">chmod +t</span>), the only people who are able to delete or rename files in '''/tmp''' are the directory's owner (typically root), the file's owner, or root. Virtually all Linux distributions enable '''/tmp''''s sticky bit by default, but you may find that the sticky bit comes in handy in other situations.
+
 
+
=== The elusive first digit ===
+
And to conclude this section, we finally take a look at the elusive first digit of a numeric mode. As you can see, this first digit is used for setting the sticky, suid, and sgid bits:
+
{| {{table}}
+
!suid
+
!sgid
+
!sticky
+
!mode digit
+
|-
+
|on
+
|on
+
|on
+
|7
+
|-
+
|on
+
|on
+
|off
+
|6
+
|-
+
|on
+
|off
+
|on
+
|5
+
|-
+
|on
+
|off
+
|off
+
|4
+
|-
+
|off
+
|on
+
|on
+
|3
+
|-
+
|off
+
|on
+
|off
+
|2
+
|-
+
|off
+
|off
+
|on
+
|1
+
|-
+
|off
+
|off
+
|off
+
|0
+
|}
+
 
+
Here's an example of how to use a 4-digit numeric mode to set permissions for a directory that will be used by a workgroup:
+
<pre>
+
# chmod 1775 /home/groupfiles
+
</pre>
+
As homework, figure out the meaning of the 1755 numeric permissions setting. :)
+
 
+
== Linux account managment ==
+
 
+
=== Introducing /etc/passwd ===
+
In this section, we'll look at the Linux account management mechanism, starting with the '''/etc/passwd''' file, which defines all the users that exist on a Linux system. You can view your own '''/etc/passwd''' file by typing less '''/etc/passwd'''.
+
 
+
Each line in '''/etc/passwd''' defines a user account. Here's an example line from my '''/etc/passwd''' file:
+
<pre>
+
drobbins:x:1000:1000:Daniel Robbins:/home/drobbins:/bin/bash
+
</pre>
+
As you can see, there is quite a bit of information on this line. In fact, each '''/etc/passwd''' line consists of multiple fields, each separated by a ''':'''.
+
 
+
The first field defines the username (drobbins), and the second field contains an x. On ancient Linux systems, this field contained an encrypted password to be used for authentication, but virtually all Linux systems now store this password information in another file.
+
 
+
The third field (1000) defines the numeric user id associated with this particular user, and the fourth field (1000) associates this user with a particular group; in a few panels, we'll see where group 1000 is defined.
+
 
+
The fifth field contains a textual description of this account -- in this case, the user's name. The sixth field defines this user's home directory, and the seventh field specifies the user's default shell -- the one that will be automatically started when this user logs in.
+
 
+
=== /etc/passwd tips and tricks ===
+
You've probably noticed that there are many more user accounts defined in '''/etc/passwd''' than actually log in to your system. This is because various Linux components use user accounts to enhance security. Typically, these system accounts have a user id ("uid") of under 100, and many of them will have something like /bin/false listed as a default shell. Since the '''/bin/false''' program does nothing but exit with an error code, this effectively prevents these accounts from being used as login accounts -- they are for internal use only.
+
 
+
=== /etc/shadow ===
+
So, user accounts themselves are defined in '''/etc/passwd'''. Linux systems contain a companion file to '''/etc/passwd''' that's called '''/etc/shadow'''. This file, unlike '''/etc/passwd''', is readable only by root and contains encrypted password information. Let's look at a sample line from '''/etc/shadow''':
+
<pre>
+
drobbins:$1$1234567890123456789012345678901:11664:0:-1:-1:-1:-1:0
+
</pre>
+
Each line defines password information for a particular account, and again, each field is separated by a :. The first field defines the particular user account with which this shadow entry is associated. The second field contains an encrypted password. The remaining fields are described in the following table:
+
{| {{table}}
+
|-
+
|field 3
+
|# of days since 1/1/1970 that the password was modified
+
|-
+
|field 4
+
|# of days before password will be allowed to be changed (0 for "change anytime")
+
|-
+
|field 5
+
|# of days before system will force user to change to a new password (-1 for "never")
+
|-
+
|field 6
+
|# of days before password expires that user will be warned about expiration (-1 for "no warning")
+
|-
+
|field 7
+
|# of days after password expiration that this account is automatically # disabled by the system (-1 for "never disable")
+
|-
+
|field 8
+
|# of days that this account has been disabled (-1 for "this account is enabled")
+
|-
+
|field 9
+
|Reserved for future use
+
|}
+
 
+
=== /etc/group ===
+
Next, we take a look at the '''/etc/group file''', which defines all the groups on a Linux system. Here's a sample line:
+
<pre>
+
drobbins:x:1000:
+
</pre>
+
The '''/etc/group field''' format is as follows. The first field defines the name of the group; the second field is a vestigial password field that now simply holds an x, and the third field defines the numeric group id of this particular group. The fourth field (empty in the above example) defines any users that are members of this group.
+
 
+
You'll recall that our sample '''/etc/passwd line''' referenced a group id of 1000. This has the effect of placing the drobbins user in the drobbins group, even though the drobbins username isn't listed in the fourth field of /etc/group.
+
 
+
=== Group notes ===
+
A note about associating users with groups: on some systems, you'll find that every new login account is associated with an identically named (and usually identically numbered) group. On other systems, all login accounts will belong to a single users group. The approach that you use on the system(s) you administrate is up to you. Creating matching groups for each user has the advantage of allowing users to more easily control access to their own files by placing trusted friends in their personal group.
+
 
+
=== Adding a user and group by hand ===
+
Now, I'll show you how to create your own user and group account. The best way to learn how to do this is to add a new user to the system manually. To begin, first make sure that your EDITOR environment variable is set to your favorite text editor:
+
<pre>
+
# echo $EDITOR
+
vim
+
</pre>
+
If it isn't, you can set EDITOR by typing something like:
+
<pre>
+
# export EDITOR=/usr/bin/emacs
+
# vipw
+
</pre>
+
You should now find yourself in your favorite text editor with the '''/etc/passwd''' file loaded up on the screen. When modifying system '''passwd''' and '''group''' files, it's very important to use the <span style="color:green">vipw</span> and <span style="color:green">vigr</span> commands. They take extra precautions to ensure that your critical '''passwd''' and '''group''' files are locked properly so they don't become corrupted.
+
 
+
=== Editing /etc/passwd ===
+
Now that you have the '''/etc/passwd''' file up, go ahead and add the following line:
+
<pre>
+
testuser:x:3000:3000:LPI tutorial test user:/home/testuser:/bin/false
+
</pre>
+
We've just added a "testuser" user with a UID of 3000. We've added him to a group with a GID of 3000, which we haven't created just yet. Alternatively, we could have assigned this user to the GID of the users group if we wanted. This new user has a comment that reads LPI tutorial test user; the user's home directory is set to /home/testuser, and the user's shell is set to /bin/false for security purposes. If we were creating an non-test account, we would set the shell to /bin/bash. OK, go ahead and save your changes and exit.
+
 
+
=== Editing /etc/shadow ===
+
Now, we need to add an entry in '''/etc/shadow''' for this particular user. To do this, type <span style="color:green">vipw -s</span>. You'll be greeted with your favorite editor, which now contains the /etc/shadow file. Now, go ahead and copy the line of an existing user account (one that has a password and is longer than the standard system account entries):
+
<pre>
+
drobbins:$1$1234567890123456789012345678901:11664:0:-1:-1:-1:-1:0
+
</pre>
+
Now, change the username on the copied line to the name of your new user, and ensure that all fields (particularly the password aging ones) are set to your liking:
+
<pre>
+
testuser:$1$1234567890123456789012345678901:11664:0:-1:-1:-1:-1:0
+
</pre>
+
Now, save and exit.
+
 
+
=== Setting a password ===
+
You'll be back at the prompt. Now, it's time to set a password for your new user:
+
<pre>
+
# passwd testuser
+
Enter new UNIX password: (enter a password for testuser)
+
Retype new UNIX password: (enter testuser's new password again)
+
</pre>
+
 
+
=== Editing /etc/group ===
+
Now that '''/etc/passwd''' and '''/etc/shadow''' are set up, it's now time to get '''/etc/group''' configured properly. To do this, type:
+
<pre>
+
# vigr
+
</pre>
+
Your '''/etc/group''' file will appear in front of you, ready for editing. Now, if you chose to assign a default group of users for your particular test user, you do not need to add any groups to '''/etc/groups'''. However, if you chose to create a new group for this user, go ahead and add the following line:
+
<pre>
+
testuser:x:3000:
+
</pre>
+
Now save and exit.
+
 
+
=== Creating a home directory ===
+
We're nearly done. Type the following commands to create testuser's home directory:
+
<pre>
+
# cd /home
+
# mkdir testuser
+
# chown testuser.testuser testuser
+
# chmod o-rwx testuser
+
</pre>
+
Our user's home directory is now in place and the account is ready for use. Well, almost ready. If you'd like to use this account, you'll need to use vipw to change testuser's default shell to '''/bin/bash''' so that the user can log in.
+
 
+
=== Account admin utils ===
+
Now that you know how to add a new account and group by hand, let's review the various time-saving account administration utilities available under Linux. Due to space constraints, we won't cover a lot of detail describing these commands. Remember that you can always get more information about a command by viewing the command's man page. If you are planning to take the LPIC 101 exam, you should spend some time getting familiar with each of these commands.
+
{| {{table}}
+
|-
+
|newgrp
+
|By default, any files that a user creates are assigned to the user's group specified in /etc/passwd. If the user belongs to other groups, he or she can type newgrp thisgroup to set current default group membership to the group thisgroup. Then, any new files created will inherit thisgroup membership.
+
|-
+
|chage
+
|The chage command is used to view and change the password aging setting stored in '''/etc/shadow'''.
+
|-
+
|gpasswd
+
|A general-purpose group administration tool.
+
|-
+
|groupadd/groupdel/groupmod
+
|Used to add/delete/modify groups in /etc/group
+
|-
+
|useradd/userdel/usermod
+
|Used to add/delete/modify users in /etc/passwd. These commands also perform various other convenience functions. See the man pages for more information.
+
|-
+
|pwconv/grpconv
+
|Used to convert passwd and group files to "new-style" shadow passwords. Virtually all Linux systems already use shadow passwords, so you should never need to use these commands.
+
|}
+
 
+
== Tuning the user environment ==
+
 
+
=== Introducing "fortune" ===
+
Your shell has many useful options that you can set to fit your personal preferences. So far, however, we haven't discussed any way to have these settings set up automatically every time you log in, except for re-typing them each time. In this section we will look at tuning your login environment by modifying startup files.
+
 
+
First, let's add a friendly message for when you first log in. To see an example message, run <span style="color:green">fortune</span>:
+
<pre>
+
$ fortune
+
No amount of careful planning will ever replace dumb luck.
+
</pre>
+
 
+
=== .bash_profile ===
+
Now, let's set up <span style="color:green">fortune</span> so that it gets run every time you log in. Use your favorite text editor to edit a file named .bash_profile in your home directory. If the file doesn't exist already, go ahead and create it. Insert a line at the top:
+
<pre>
+
fortune
+
</pre>
+
Try logging out and back in. Unless you're running a display manager like xdm, gdm, or kdm, you should be greeted cheerfully when you log in:
+
<pre>
+
mycroft.flatmonk.org login: chouser
+
Password:
+
Freedom from incrustations of grime is contiguous to rectitude.
+
$
+
</pre>
+
 
+
=== The login shell ===
+
When bash started, it walked through the '''.bash_profile''' file in your home directory, running each line as though it had been typed at a bash prompt. This is called sourcing the file.
+
 
+
Bash acts somewhat differently depending on how it is started. If it is started as a login shell, it will act as it did above -- first sourcing the system-wide '''/etc/profile''', and then your personal '''~/.bash_profile'''.
+
 
+
There are two ways to tell bash to run as a login shell. One way is used when you first log in: bash is started with a process name of -bash. You can see this in your process listing:
+
<pre>
+
$ ps u
+
USER      PID %CPU %MEM  VSZ  RSS TTY      STAT START  TIME COMMAND
+
chouser    404  0.0  0.0  2508  156 tty2    S    2001  0:00 -bash
+
</pre>
+
You will probably see a much longer listing, but you should have at least one COMMAND with a dash before the name of your shell, like -bash in the example above. This dash is used by the shell to determine if it's being run as a login shell.
+
 
+
=== Understanding --login ===
+
The second way to tell bash to run as a login shell is with the <span style="color:green">--login</span> command-line option. This is sometimes used by terminal emulators (like xterm) to make their bash sessions act like initial login sessions.
+
 
+
After you have logged in, more copies of your shell will be run. Unless they are started with <span style="color:green">--login</span> or have a dash in the process name, these sessions will not be login shells. If they give you a prompt, however, they are called interactive shells. If bash is started as interactive, but not login, it will ignore '''/etc/profile''' and '''~/.bash_profile''' and will instead source '''~/.bashrc'''.
+
{| {{table}}
+
!interactive
+
!login
+
!profile
+
!rc
+
|-
+
|yes
+
|yes
+
|source
+
|ignore
+
|-
+
|yes
+
|no
+
|ignore
+
|source
+
|-
+
|no
+
|yes
+
|source
+
|ignore
+
|-
+
|no
+
|no
+
|ignore
+
|ignore
+
|}
+
 
+
=== Testing for interactivity ===
+
Sometimes bash sources your '''~/.bashrc''', even though it isn't really interactive, such as when using commands like rsh and scp. This is important to keep in mind because printing out text, like we did with the fortune command earlier, can really mess up these non-interactive bash sessions. It's a good idea to use the PS1 variable to detect whether the current shell is truly interactive before printing text from a startup file:
+
<pre>
+
if [ -n "$PS1" ]; then
+
fortune
+
fi
+
</pre>
+
 
+
=== /etc/profile and /etc/skel ===
+
As a system administrator, you are in charge of '''/etc/profile'''. Since it is sourced by everyone when they first log in, it is important to keep it in working order. It is also a powerful tool in making things work correctly for new users as soon as they log into their new account.
+
 
+
However, there are some settings that you may want new users to have as defaults, but also allow them to change easily. This is where the '''/etc/skel''' directory comes in. When you use the <span style="color:green">useradd</span> command to create a new user account, it copies all the files from '''/etc/skel''' into the user's new home directory. That means you can put helpful '''.bash_profile''' and '''.bashrc''' files in '''/etc/skel''' to get new users off to a good start.
+
 
+
=== export ===
+
Variables in bash can be marked so that they are set the same in any new shells that it starts; this is called being marked for export. You can have bash list all of the variables that are currently marked for export in your shell session:
+
<pre>
+
$ export
+
declare -x EDITOR="vim"
+
declare -x HOME="/home/chouser"
+
declare -x MAIL="/var/spool/mail/chouser"
+
declare -x PAGER="/usr/bin/less"
+
declare -x PATH="/bin:/usr/bin:/usr/local/bin:/home/chouser/bin"
+
declare -x PWD="/home/chouser"
+
declare -x TERM="xterm"
+
declare -x USER="chouser"
+
</pre>
+
 
+
=== Marking variables for export ===
+
If a variable is not marked for export, any new shells that it starts will not have that variable set. However, you can mark a variable for export by passing it to the <span style="color:green">export</span> built-in:
+
<pre>
+
$ FOO=foo
+
$ BAR=bar
+
$ export BAR
+
$ echo $FOO $BAR
+
foo bar
+
$ bash
+
$ echo $FOO $BAR
+
bar
+
</pre>
+
In this example, the variables FOO and BAR were both set, but only BAR was marked for export. When a new bash was started, it had lost the value for FOO. If you exit this new bash, you can see that the original one still has values for both FOO and BAR:
+
<pre>
+
$ exit
+
$ echo $FOO $BAR
+
foo bar
+
</pre>
+
 
+
=== Export and set -x ===
+
Because of this behavior, variables can be set in '''~/.bash_profile''' or '''/etc/profile''' and marked for export, and then never need to be set again. There are some options that cannot be exported, however, and so they must be put in your '''~/.bashrc''' and your ''profile'' in order to be set consistently. These options are adjusted with the set built-in:
+
<pre>
+
$ set -x
+
</pre>
+
The <span style="color:green">-x</span> option causes bash to print out each command it is about to run:
+
<pre>
+
$ echo $FOO
+
$ echo foo
+
foo
+
</pre>
+
This can be very useful for understanding unexpected quoting behavior or similar strangeness. To turn off the <span style="color:green">-x</span> option, do <span style="color:green">set +x</span>. See the bash man page for all of the options to the set built-in.
+
 
+
=== Setting variables with "set" ===
+
The <span style="color:green">set</span> built-in can also be used for setting variables, but when used that way, it is optional. The bash command <span style="color:green">set FOO=foo</span> means exactly the same as <span style="color:green">FOO=foo</span>. Un-setting a variable is done with the <span style="color:green">unset</span> built-in:
+
<pre>
+
$ FOO=bar
+
$ echo $FOO
+
bar
+
$ unset FOO
+
$ echo $FOO
+
</pre>
+
 
+
=== Unset vs. FOO= ===
+
This is ''not'' the same as setting a variable to nothing, although it is sometimes hard to tell the difference. One way to tell is to use the <span style="color:green">set</span> built-in with no parameters to list all current variables:
+
<pre>
+
$ FOO=bar
+
$ set | grep ^FOO
+
FOO=bar
+
$ FOO=
+
$ set | grep ^FOO
+
FOO=
+
$ unset FOO
+
$ set | grep ^FOO
+
</pre>
+
Using <span style="color:green">set</span> with no parameters like this is similar to using the <span style="color:green">export</span> built-in, except that <span style="color:green">set</span> lists all variables instead of just those marked for export.
+
 
+
=== Exporting to change command behavior ===
+
Often, the behavior of commands can be altered by setting environment variables. Just as with new bash sessions, other programs that are started from your bash prompt will only be able to see variables that are marked for export. For example, the command <span style="color:green">man</span> checks the variable PAGER to see what program to use to step through the text one page at a time.
+
<pre>
+
$ PAGER=less
+
$ export PAGER
+
$ man man
+
</pre>
+
With PAGER set to <span style="color:green">less</span>, you will see one page at a time, and pressing the space bar moves on to the next page. If you change PAGER to <span style="color:green">cat</span>, the text will be displayed all at once, without stopping.
+
<pre>
+
$ PAGER=cat
+
$ man man
+
</pre>
+
 
+
=== Using "env" ===
+
Unfortunately, if you forget to set PAGER back to <span style="color:green">less</span>, <span style="color:green">man</span> (as well as some other commands) will continue to display all their text without stopping. If you wanted to have PAGER set to <span style="color:green">cat</span> just once, you could use the <span style="color:green">env</span> command:
+
<pre>
+
$ PAGER=less
+
$ env PAGER=cat man man
+
$ echo $PAGER
+
less
+
</pre>
+
This time, PAGER was exported to <span style="color:green">man</span> with a value of <span style="color:green">cat</span>, but the PAGER variable itself remained unchanged in the bash session.
+
 
+
== Summary and resources ==
+
 
+
=== Summary ===
+
Congratulations on finishing Part 3 of this tutorial series! At this point, you should know how to locate information in system and Internet documentation, and you should have a good grasp of the Linux permissions model, user account management, and login environment tuning.
+
 
+
=== Resources ===
+
Be sure to check out the various Linux documentation resources covered in this tutorial -- particularly the [http://www.tldp.org/ Linux Documentation Project]. You'll find its collection of guides, HOWTOs, FAQs, and man pages to be invaluable. Be sure to check out [http://www.lwn.net/ Linux Weekly News] as well.
+
 
+
The [http://www.tldp.org/guides.html Linux System Administrators guide] (available from the "Guides" section at www.tldp.org) is a good complement to this series of tutorials -- give it a read! You may also find Eric S. Raymond's [http://www.tldp.org/HOWTO/Unix-and-Internet-Fundamentals-HOWTO/ Unix and Internet Fundamentals HOWTO] to be helpful.
+
 
+
Check out the other articles in this series:
+
*[[Linux Fundamentals, Part 1]]
+
*[[Linux Fundamentals, Part 2]]
+
*[[Linux Fundamentals, Part 4]]
+
 
+
In the "Bash by Example" article series, Daniel shows you how to use bash programming constructs to write your own bash scripts. This series (particularly Parts 1 and 2) will be good preparation for the LPIC Level 1 exam:
+
*[[Bash by Example, Part 1]]: Fundamental programming in the Bourne-again shell
+
*[[Bash by Example, Part 2]]: More bash programming fundamentals
+
*[[Bash by Example, Part 3]]: Exploring the ebuild system
+
 
+
You can learn more about sed in the Sed by Example article series. If you're planning to take the LPI exam, be sure to read the first two articles of this series.
+
*[[Sed by Example, Part 1]]
+
*[[Sed by Example, Part 2]]
+
*[[Sed by Example, Part 3]]
+
 
+
To learn more about awk, read the Awk by Example article series.
+
*[[Awk by Example, Part 1]]
+
*[[Awk by Example, Part 2]]
+
*[[Awk by Example, Part 3]]
+
 
+
If you're not too familiar with the vi editor, I strongly recommend that you check out my [http://www-106.ibm.com/developerworks/edu/l-dw-linuxvi-i.html Vi -- the cheat sheet method] tutorial. This tutorial will give you a gentle yet fast-paced introduction to this powerful text editor. Consider this must-read material if you don't know how to use vi.
+
 
+
__NOTOC__
+
[[Category:Linux Core Concepts]]
+
[[Category:Articles]]
+
{{ArticleFooter}}
+

Latest revision as of 05:25, May 30, 2015

Often, a Funtoo developer needs to fork an upstream ebuild. This is necessary when we want to apply fixes to it. This page will explain the concepts of forking and how this works in the context of Funtoo.

Portage Tree Generation

Funtoo Linux generates its Portage tree using a special script that essentially takes a Gentoo tree as its starting point, and then applies various modifications to it. The modifications involve adding packages from various overlays, including our Funtoo-overlay. Some packages added are brand new, while other packages are our special forked versions that replace existing packages.

In the vast majority of cases, when we fork a package, we take full responsibility for all ebuilds associated with that package, meaning that we have a full copy of the sys-foo/bar directory in one of our overlays.

If you're interested in seeing the actual script that does all these things, take a look at the following files:

http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/current-update.sh
cronned script that calls merge.py.
http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge.py
python script that does the heavy lifting of combining Gentoo tree with various overlays, including our flora and funtoo-overlay. When we want to change what overlays we merge, what packages we exclude as a matter of policy (such as stale packages in some overlays), we make changes to this file.
http://git.funtoo.org/funtoo-overlay/tree/funtoo/scripts/merge_utils.py
python module that contains classes and methods that implement the merging functionality.

Forking an Ebuild

In general, we fork ebuilds from Gentoo that we want to modify in some way. Before you fork an ebuild, it's important to understand that in general we fork entire packages, not just a single ebuild. This means that if you want to make some changes to sys-foo/bar, you are going to fork all sys-foo/bar ebuilds, and then Funtoo will be responsible for continuing to maintain these ebuilds until the package is unforked. Here are the steps we would use to fork sys-foo/bar:

  1. Find sys-foo/bar in you regular Portage tree. Make sure you have run emerge --sync recently to ensure it is up-to-date. If you want to fork from very recent changes that are not yet in our tree, you may need to grab the most recent Gentoo Portage tree to serve as your source for sys-foo/bar (this typically isn't necessary.)
# alias to recursively grab latest from Gentoo Portage tree WITHOUT history
# usage: getgen gentoo-x86/dev-db/mongodb
alias getgen="cvs -d :pserver:anonymous@anoncvs.gentoo.org:/var/cvsroot export -D$(date '+%Y-%m-%d')"
  1. Copy the sys-foo/bar directory in its entirety to funtoo-overlay/sys-foo/bar.
  2. Make any necessary modifications to funtoo-overlay/sys-foo/bar.
  3. Perform some funtoo-ification steps prior to commit.
  4. Add and commit the changes to funtoo-overlay.
  5. Push changes to funtoo-overlay.

At this point, the forked sys-foo/bar package will be part of funtoo-overlay. The next time our unified Portage tree is generated by merge.py (the one that users have in their /usr/portage and is updated via emerge --sync), your forked ebuild will be used in place of the Gentoo ebuild. Why is this? It is because our merge.py script has been defined with a policy that any ebuilds in funtoo-overlay will replace any existing Gentoo ebuilds if they exist. The mechanism of replacement is that our sys-foo/bar directory will be used in place of Gentoo's sys-foo/bar directory. So this is how the forking process works.

Funtoo-ification

When we fork a package from Gentoo, we perform the following tweaks to the package directory before committing:

  1. Removal of ChangeLog.
  2. Run ebuild foo-1.0.ebuild digest before committing. This will cause the Manifest file to be regenerated. Gentoo has a lot more entries in this file than we do, since we use mini-Manfiests that only include DIST listings (for distfiles only.) We want to commit our mini-Manifest (still called Manifest, just with less entries in it) rather than the one that came from Gentoo.
  3. Edit the top of each ebuild, and remove all Copyright and $Header: lines at the top of the file. We have a LICENSE.txt and COPYRIGHT.txt file in the root of our Portage tree, which is easier to maintain than keeping all the years up-to-date in each ebuild. Also, the $Header: line is there for the CVS version control system in Gentoo which Funtoo does not use. The only comment that should remain on the top of the ebuild is the one stating that it is distributed under the GPLv2..
# If you find yourself doing this often, place this function in your .bashrc, .zshrc, etc
funtooize() {
    if [ -z "$1" ]; then
        search_path='.'
    else
        search_path=$1
    fi

    find $search_path -type f -exec sed -i -e '/^# Copyright\|^# \$Header/d' {} +
    find $search_path -type f -name "ChangeLog*" -delete
    find $search_path -type f -name '*.ebuild' -exec ebuild {} manifest \;
}

Here are a few additional changes that you are allowed to make to any forked ebuilds:

  1. Line length greater than 80 characters. Gentoo enforces an 80-character line length limit. We don't.
  2. KEYWORDS of * and ~*. Gentoo does not allow these shortcuts. We do. They allow you to say "all arches" and "all unstable arches" in a concise way. Gentoo doesn't allow these shortcuts because it's Gentoo's policy to have each arch team manually approve each package. We do not have this policy so we can use the shortcuts.
  3. Use of 4-python EAPI. We allow the use of this EAPI for enhanced python functionality.