https://www.funtoo.org/api.php?action=feedcontributions&user=Shamus397&feedformat=atomFuntoo - User contributions [en]2024-03-29T02:22:01ZUser contributionsMediaWiki 1.36.2https://www.funtoo.org/index.php?title=Mail_Server&diff=38628Mail Server2022-01-25T15:02:08Z<p>Shamus397: Add note about port 25 and alt port 587</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl mysql pam ssl<br />
net-mail/dovecot bzip2 maildir mysql pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom of {{f|/etc/postfix/main.cf}}:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (we will be changing the defaults in the file to what's shown here). Since this is a new install, the developers recommended that the {{c|compatibility_level}} be set to 2:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
}}<br />
<br />
Next, we will be setting up the mail server's hostname and domain. How we fill this in depends on what your DNS and MX records point to. If you have it set up so that your main domain is of the form ''tld.ext'', then you will put that into the {{c|mydomain}} field, otherwise, you will set it the same as the {{c|myshostname}} field (in ''host.tld.ext'' form):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
myhostname = <my.fqdn.com><br />
mydomain = <fqdn.com {{!}} my.fqdn.com><br />
}}<br />
<br />
The {{c|mydestination}} field '''MUST''' be set to localhost, otherwise, incoming mail will bounce:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mydestination = localhost # This MUST be set to localhost<br />
}}<br />
<br />
Some mail servers will not talk to you if the hostname that is set up on your reverse DNS record does not match the SMTP banner that Postfix sends to peers. To fix that, add the following (replace ''<reverse DNS hostname>'' with your real reverse DNS hostname):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=And yet more Postfix configuration|body=<br />
smtpd_banner = <reverse DNS hostname> ESMTP $mail_name<br />
}}<br />
<br />
{{note|It is not necessary for the reverse DNS hostname to match your mail server's hostname; it just has to be present.}}<br />
<br />
Finally, in this file, we have to enumerate the networks that can relay mail via our server. Generally we want to list ''only'' the subnets that we want to be able to send mail from (replace ''<LAN IP>'' with your LAN's subnet and ''<LAN netmask>'' with your LAN's netmask, and leave 127.0.0.0/8 in):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mynetworks = <LAN IP>/<LAN netmask>, 127.0.0.0/8<br />
}}<br />
<br />
{{note|If you want one or more remote hosts to be able to send through your mail server, you should add them to the {{c|mynetworks}} line as comma separated values. Also, you should set the netmask (the part after the '/') on each of them to 32, to ensure that ''only'' those IP addresses can be sent from.}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
If we want Postfix to talk on port 25, we have to make sure that the second field in the line in {{f|/etc/postfix/master.cf}} for smtp is {{c|inet}}:<br />
<br />
{{file|name=/etc/postfix/master.cf|desc=Postfix master service file|body=<br />
# ==========================================================================<br />
# service type private unpriv chroot wakeup maxproc command + args<br />
# (yes) (yes) (no) (never) (100)<br />
# ==========================================================================<br />
smtp inet n - y - - smtpd<br />
}}<br />
<br />
{{note|Some ISPs block port 25; in that case you would uncomment the line in master.cf that starts with "submission" (remove the '#' character in front of it) to enable postfix communicating on port 587.}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}. We need to tell Dovecot where to store mail (and, in the case of IMAP, keep it). {{c|mail_location}} and {{c|mail_privileged_group}} will likely be in there already and need to be changed; we will likely have to add {{c|first_valid_uid}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/conf.d/10-auth.conf}}: Here we have to tell Dovecot how we want to authenticate our users. Note that in addition to setting {{c|disable_plaintext_auth}} to ''yes'' and {{c|auth_mechanisms}} to ''plain login'', we need to comment out (by inserting a '#' in front of) the line {{c|!include auth-system.conf.ext}} and uncomment (by removing any '#' in front of) the line {{c|!include auth-sql.conf.ext}}. This is to prevent Dovecot from using native accounts for authorization and use our database instead:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#!include auth-system.conf.ext<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
Next we need to edit {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}, so Dovecot knows where and how the passwords are stored, and how and where to write our users' mail:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/dovecot-sql.conf.ext}}, which is mentioned in the previous file. This is to tell Dovecot the details of how to talk to the database in order to validate user logins (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next file we have to modify is {{f|/etc/dovecot/conf.d/10-master.conf}}. First, we will set the listener ports for IMAP and POP3 to zero, to force encrypted links:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
}}<br />
<br />
Next, we have to configure Dovecot's LMTP service:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
}}<br />
<br />
Finally, we need to properly set up the {{c|auth}} and {{c|auth-worker}} services:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, we need to edit {{f|/etc/dovecot/conf.d/10-ssl.conf}}, so that Dovecot knows where to find valid certificates to work with:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, the certificates generated this way are self-signed; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Upgrade_Instructions/1.2-release&diff=26717Upgrade Instructions/1.2-release2019-01-28T18:04:55Z<p>Shamus397: Add instructions for when update doesn't work because of incompatible C++ abi changes</p>
<hr />
<div><languages/><br />
<translate><br />
<!--T:1--><br />
{{Important|The goal of these instructions is to provide Funtoo Linux users with a reliable, consistent set of instructions for upgrading Funtoo Linux from 1.0 to 1.2. Please assist in ensuring that these instructions are complete and guide users through any potential complications. Since this is a wiki, make changes to the page that are needed to make these instructions 100% reliable. Thank you!}}<br />
<br />
<!--T:2--><br />
These instructions will guide you through the process of upgrading your system from Funtoo Linux 1.0 to 1.2. First, please make sure that you have created a backup of your system. If you choose to proceed without<br />
a backup, then you are assuming the risk of a broken system and dealing with fixing it or re-installing. While these install steps are fairly robust, we will<br />
be removing what appear to be unused packages on the system, and while every precaution is taken to avoid breaking packages, in odd cases this could result in some packages being removed that you actually need. Typically<br />
this will not happen, but since the possibility exists, it is best to be prepared for this possibility, particularly on critical systems.<br />
<br />
<!--T:3--><br />
Now, edit your {{f|/var/lib/portage/world}} file. Look for catpkgs (ie. "category/packagename") that you no longer use or need on your system and remove them. Also consider packages you may have installed<br />
with {{c|--oneshot}} that are not in the world file but should be, and add them. Portage will use {{f|/var/lib/portage/world}} as the master list of packages that should be on<br />
your system. We will now look into cleaning up any unnecessary packages that are not in the world set. We want to remove these packages for a couple of reasons. First,<br />
they will not get upgraded with a {{c|@world}} update. Second, because they are not included in {{c|@world}}, they could be outdated and have old and problematic dependencies that could hamper our upgrade, since portage will not want to "break" dependencies for these orphaned packages. Third, when we do an {{c|emerge @preserved-rebuild}}, we may end up rebuilding packages that we don't need. So removing unnecessary packages is a good idea for quite a few reasons.<br />
<br />
<!--T:4--><br />
{{Note|You may be wondering -- what are these packages on my system that are not part of the world set? They could be a number of things. First, they could be build dependencies for certain packages. They could possibly be old slots of packages you already use -- for example, an old version of PHP. The could also be packages that were dependencies of certain packages, but are no longer needed by those packages -- possibly due to changes in {{c|USE}} flags. Often, virtuals are part of this group of packages, and it is generally safe for virtuals to be removed. They will get re-emerged in the future if referenced by an ebuild.}}<br />
<br />
<!--T:5--><br />
Run the following command and carefully review its output. Do not say "y" at this point:<br />
<br />
<!--T:6--><br />
{{console|body=<br />
# ##i##emerge -p --depclean --ignore-soname-deps=n | less<br />
}}<br />
<br />
<!--T:7--><br />
{{Note|The {{c|1=--ignore-soname-deps=n}} option will prevent packages that provide necessary libraries from being removed, even if they appear to be "orphaned." This is an additional safety measure when cleaning dependencies from your system.}}<br />
<br />
<!--T:8--><br />
Now, review the list of packages that are going to be removed. See anything in this list that you know you need? This would indicate that you need to add the cat/pkg<br />
to {{f|/var/lib/portage/world}} before proceeding. Once the list looks OK, type:<br />
<br />
<!--T:9--><br />
{{console|body=<br />
# ##i##emerge -a --depclean --ignore-soname-deps=n<br />
}}<br />
<br />
<!--T:10--><br />
...And type "y" [enter] to remove old packages.<br />
<br />
<!--T:11--><br />
Now, you should have a still-functioning system, but with all "extra" packages removed. Now it is time to upgrade the packages that remain. <br />
<br />
<!--T:12--><br />
Now you will want to run {{c|ego sync}} and upgrade to the latest ego-2.4.x series available. <br />
{{console|body=<br />
# ##i## ego sync<br />
# ##i## emerge -C boot-update<br />
# ##i## emerge -v1 ego<br />
}}<br />
<br />
<!--T:13--><br />
If you have difficulty satisfying deps for it for whatever reason, the following should work:<br />
{{console|body=<br />
# ##i## emerge -C boot-update<br />
# ##i## emerge -v1 --nodeps ego<br />
}}<br />
<br />
<!--T:14--><br />
If you still cannot merge using emerge, the following should work (note that this will fail if you don't have the ebuild in your tree, and ego thinks it is at its highest revision):<br />
{{console|body=<br />
# ##i## cd /var/git/meta-repo/kits/core-kit/app-admin/ego<br />
# ##i## ebuild ego-2.6.3.ebuild merge<br />
}}<br />
<br />
If the foregoing fails, this will definitely pull in the latest ego and allow you to sync properly:<br />
{{console|body=<br />
# ##i## git clone https://github.com/funtoo/ego.git<br />
# ##i## cd ego<br />
# ##i## ./ego sync<br />
}}<br />
<br />
Once the new ego is merged, edit your /etc/ego.conf to look like this:<br />
<br />
<!--T:15--><br />
{{file|name=/etc/ego.conf|body=<br />
[global]<br />
<br />
<!--T:16--><br />
release = 1.2<br />
}}<br />
<br />
<!--T:17--><br />
Now, run the following steps as root.<br />
<br />
<!--T:18--><br />
{{console|body=<br />
# ##i##ego sync<br />
}}<br />
<br />
<!--T:19--><br />
This will activate the new 1.2 kits. Now, time to start upgrading:<br />
<br />
<!--T:20--><br />
{{console|body=<br />
# ##i##emerge -u1 gcc<br />
}}<br />
<br />
<!--T:21--><br />
This will upgrade gcc.<br />
<br />
<!--T:22--><br />
This is an ideal time to review the subarch setting of your Funtoo Linux installation. Funtoo Linux 1.2 now has optimizations available for 5th and 6th-generation Intel<br />
Core processors, as well as Ryzen processors. View your current subarch, as well as available subarches, by typing the following command:<br />
<br />
<!--T:23--><br />
{{console|body=<br />
# ##i##ego profile list subarch<br />
<br />
=== ##g##subarch##!g##: === <!--T:24--><br />
<br />
<!--T:25--><br />
amd64-bulldozer, amd64-excavator, amd64-jaguar, amd64-k10<br />
amd64-k8, amd64-k8+sse3, amd64-piledriver, amd64-steamroller<br />
amd64-zen, atom_64, btver1_64, core-avx-i, core2_64, corei7<br />
generic_64, intel64-broadwell, intel64-haswell, intel64-ivybridge<br />
intel64-nehalem, intel64-sandybridge, intel64-silvermont, intel64-skylake<br />
##c##intel64-westmere##!c##*, native_64, nocona, opteron_64, xen-pentium4+sse3_64<br />
<br />
<!--T:26--><br />
#<br />
}}<br />
<br />
<!--T:27--><br />
If desired and supported by your CPU, you can now update your subarch to a more optimized subarch for your hardware. The new subarch profiles available are:<br />
<br />
<!--T:28--><br />
* {{c|intel64-skylake}} - Optimized for Intel Core 6th Generation Processors (see [[intel64-skylake]] for more info.)<br />
* {{c|intel64-broadwell}} - Optimized for Intel Core 5th Generation Processors (see [[intel64-broadwell]] for more info.)<br />
* {{c|amd64-zen}} - Optimized for AMD Ryzen Processors.<br />
<br />
<!--T:29--><br />
Use the {{c|lscpu}} command to view information about your CPU and do a web search for its name to determine what generation CPU it is. Then, the system's subarch<br />
can be changed as follows:<br />
<br />
{{console|body=<br />
# ##i##ego profile subarch intel64-skylake<br />
=== ##g##Enabled Profiles##!g##: === <!--T:30--><br />
<br />
<!--T:31--><br />
##b##arch##!b##: ##c##x86-64bit<br />
##b##build##!b##: ##c##current<br />
##b##subarch##!b##: ##c##intel64-skylake<br />
##b##flavor##!b##: ##c##core<br />
<br />
<!--T:32--><br />
>>> Set subarch to intel64-skylake.<br />
##b##Updating profiles at /etc/portage/make.profile/parent...<br />
<br />
<!--T:33--><br />
#<br />
}}<br />
<br />
<!--T:34--><br />
Now that we have ensured that we have an optimal subarch set for your system, it's time to begin the process of rebuilding critical packages with the new compiler. We will start with glibc. Enter the following command:<br />
<br />
<!--T:35--><br />
{{console|body=<br />
# ##i##emerge -u1 glibc libnsl libtirpc rpcsvc-proto<br />
}}<br />
<br />
<!--T:36--><br />
Glibc and its dependencies/related packages will now be upgraded.<br />
<br />
<!--T:37--><br />
Since moving to 1.2 also includes moving to python-3.6, perform the following steps:<br />
<br />
<!--T:38--><br />
{{console|body=<br />
# ##i##emerge -u1 =dev-lang/python-3.6*<br />
# ##i##emerge -C =dev-lang/python-3.4*<br />
}}<br />
<br />
<!--T:39--><br />
This will ensure that we have python-3.6 ready and installed, and the older python-3.4 removed. Removing python-3.4 is important to ensure that python modules upgrade properly.<br />
<br />
<!--T:40--><br />
Some packages rely on a current ruby being available on the system, and having stale versions on your system can cause problems. To remove these from your system, run:<br />
<br />
<!--T:41--><br />
{{console|body=<br />
# ##i##emerge -C \<=dev-lang/ruby-2.3.0<br />
}}<br />
<br />
<!--T:42--><br />
For upgrading to 1.2, you<br />
have to rebuild all packages, which will ensure that your system is fully optimized with the new gcc.<br />
<br />
<!--T:43--><br />
{{Note|Include the {{c|1=--jobs=3}} (or higher number) option as a parameter to the {{c|emerge}} command if you have sufficient RAM and CPU cores to build several packages in parallel.}}<br />
<br />
<!--T:44--><br />
Here is what you need to run:<br />
<br />
<!--T:45--><br />
{{console|body=<br />
# ##i##emerge --emptytree -a @world<br />
}}<br />
<br />
<!--T:46--><br />
This will fully rebuild all packages on your system. It will take a lot of time, but will ensure everything is freshly rebuilt. Once completed successfully, this will result in an up-to-date system, with potentially better-optimized binaries, benefiting from more recent gcc improvements.<br />
<br />
<!--T:47--><br />
{{Note|If the preceding command fails, you should run 'emerge -uDN1 --keep-going @world' to ensure that all dependencies are fully resolved and rebuilt, then run the 'emerge --emptytree -a @world' command again to ensure that every package is rebuilt with the new gcc compiler. If *that* fails, you might need to run revdep-rebuild --library 'libstdc++.so.6' -- --exclude gcc in order to update the C++ abi for the new gcc.}}<br />
<br />
<!--T:48--><br />
Finally, you will want to either run {{c|etc-update}} or {{c|dispatch-conf}}:<br />
<br />
<!--T:49--><br />
{{console|body=<br />
# ##i##etc-update<br />
}}<br />
<br />
<!--T:50--><br />
If your kernel has been upgraded, make the necessary changes to {{f|/etc/boot.conf}} to make the new kernel the default, and then re-run {{c|ego boot update}}:<br />
<br />
<!--T:51--><br />
{{console|body=<br />
# ##i##ego boot update<br />
}}<br />
<br />
<!--T:52--><br />
Now is a good time to perform a pre-check of any packages that have been installed that may require configuration file updates. One notable example is php-fpm -- you may need to perform the following steps if your system uses php-fpm:<br />
<br />
<!--T:53--><br />
{{console|body=<br />
# ##i##cp /etc/php/fpm-php-7.1/php* /etc/php/fpm-php-7.3/php*<br />
}}<br />
<br />
<!--T:54--><br />
This will ensure that the settings you use for the previously-installed version of php-fpm will be applied to the current version.<br />
<br />
<!--T:55--><br />
{{Note|If you find any other packages that need similar manual steps post-upgrade, please document them here for the benefit of others! Thanks.}}<br />
<br />
<!--T:56--><br />
At this point, the migration to 1.2 should be complete. At a convenient time, reboot your system, and perform a thorough check of all services to ensure they have started<br />
correctly:<br />
<br />
<!--T:57--><br />
{{console|body=<br />
# ##i##reboot<br />
}}<br />
<br />
<!--T:58--><br />
After reboot:<br />
<br />
<!--T:59--><br />
{{console|body=<br />
# ##i##rc-status<br />
}}<br />
<br />
<!--T:60--><br />
Now, perform a final check of any production services to ensure that they are operating properly, by loading web pages, sending test emails, etc.<br />
<br />
<!--T:61--><br />
At this point, you are now upgraded to Funtoo Linux 1.2! Please report any bugs to https://bugs.funtoo.org and let us know of any issues you experience, either as part of the upgrade, related to dependencies, or related to functionality on your upgraded system.<br />
<br />
<!--T:62--><br />
[[Category:Official Documentation]]<br />
[[Category:Upgrade Instructions]]<br />
</translate></div>Shamus397https://www.funtoo.org/index.php?title=Upgrade_Instructions/1.2-release&diff=25816Upgrade Instructions/1.2-release2018-11-26T23:57:18Z<p>Shamus397: Add help for when ego 2.6.x ebuilds are not available because ego sync doesn't pull new ones.</p>
<hr />
<div><languages/><br />
<translate><br />
<!--T:1--><br />
{{Important|The goal of these instructions is to provide Funtoo Linux users with a reliable, consistent set of instructions for upgrading Funtoo Linux from 1.0 to 1.2. Please assist in ensuring that these instructions are complete and guide users through any potential complications. Since this is a wiki, make changes to the page that are needed to make these instructions 100% reliable. Thank you!}}<br />
<br />
<!--T:2--><br />
These instructions will guide you through the process of upgrading your system from Funtoo Linux 1.0 to 1.2. First, please make sure that you have created a backup of your system. If you choose to proceed without<br />
a backup, then you are assuming the risk of a broken system and dealing with fixing it or re-installing. While these install steps are fairly robust, we will<br />
be removing what appear to be unused packages on the system, and while every precaution is taken to avoid breaking packages, in odd cases this could result in some packages being removed that you actually need. Typically<br />
this will not happen, but since the possibility exists, it is best to be prepared for this possibility, particularly on critical systems.<br />
<br />
<!--T:3--><br />
Now, edit your {{f|/var/lib/portage/world}} file. Look for catpkgs (ie. "category/packagename") that you no longer use or need on your system and remove them. Also consider packages you may have installed<br />
with {{c|--oneshot}} that are not in the world file but should be, and add them. Portage will use {{f|/var/lib/portage/world}} as the master list of packages that should be on<br />
your system. We will now look into cleaning up any unnecessary packages that are not in the world set. We want to remove these packages for a couple of reasons. First,<br />
they will not get upgraded with a {{c|@world}} update. Second, because they are not included in {{c|@world}}, they could be outdated and have old and problematic dependencies that could hamper our upgrade, since portage will not want to "break" dependencies for these orphaned packages. Third, when we do an {{c|emerge @preserved-rebuild}}, we may end up rebuilding packages that we don't need. So removing unnecessary packages is a good idea for quite a few reasons.<br />
<br />
<!--T:4--><br />
{{Note|You may be wondering -- what are these packages on my system that are not part of the world set? They could be a number of things. First, they could be build dependencies for certain packages. They could possibly be old slots of packages you already use -- for example, an old version of PHP. The could also be packages that were dependencies of certain packages, but are no longer needed by those packages -- possibly due to changes in {{c|USE}} flags. Often, virtuals are part of this group of packages, and it is generally safe for virtuals to be removed. They will get re-emerged in the future if referenced by an ebuild.}}<br />
<br />
<!--T:5--><br />
Run the following command and carefully review its output. Do not say "y" at this point:<br />
<br />
<!--T:6--><br />
{{console|body=<br />
# ##i##emerge -p --depclean --ignore-soname-deps=n | less<br />
}}<br />
<br />
<!--T:7--><br />
{{Note|The {{c|1=--ignore-soname-deps=n}} option will prevent packages that provide necessary libraries from being removed, even if they appear to be "orphaned." This is an additional safety measure when cleaning dependencies from your system.}}<br />
<br />
<!--T:8--><br />
Now, review the list of packages that are going to be removed. See anything in this list that you know you need? This would indicate that you need to add the cat/pkg<br />
to {{f|/var/lib/portage/world}} before proceeding. Once the list looks OK, type:<br />
<br />
<!--T:9--><br />
{{console|body=<br />
# ##i##emerge -a --depclean --ignore-soname-deps=n<br />
}}<br />
<br />
<!--T:10--><br />
...And type "y" [enter] to remove old packages.<br />
<br />
<!--T:11--><br />
Now, you should have a still-functioning system, but with all "extra" packages removed. Now it is time to upgrade the packages that remain. <br />
<br />
<!--T:12--><br />
Now you will want to run {{c|ego sync}} and upgrade to the latest ego-2.4.x series available. <br />
{{console|body=<br />
# ##i## ego sync<br />
# ##i## emerge -C boot-update<br />
# ##i## emerge -v1 ego<br />
}}<br />
<br />
<!--T:13--><br />
If you have difficulty satisfying deps for it for whatever reason, the following should work:<br />
{{console|body=<br />
# ##i## emerge -C boot-update<br />
# ##i## emerge -v1 --nodeps ego<br />
}}<br />
<br />
<!--T:14--><br />
If you still cannot merge using emerge, the following should work (note that this will fail if you don't have the ebuild in your tree, and ego thinks it is at its highest revision):<br />
{{console|body=<br />
# ##i## cd /var/git/meta-repo/kits/core-kit/app-admin/ego<br />
# ##i## ebuild ego-2.6.3.ebuild merge<br />
}}<br />
<br />
If the foregoing fails, this will definitely pull in the latest ego and allow you to sync properly:<br />
{{console|body=<br />
# ##i## git clone https://github.com/funtoo/ego.git<br />
# ##i## cd ego<br />
# ##i## ./ego sync<br />
}}<br />
<br />
Once the new ego is merged, edit your /etc/ego.conf to look like this:<br />
<br />
<!--T:15--><br />
{{file|name=/etc/ego.conf|body=<br />
[global]<br />
<br />
<!--T:16--><br />
release = 1.2<br />
}}<br />
<br />
<!--T:17--><br />
Now, run the following steps as root.<br />
<br />
<!--T:18--><br />
{{console|body=<br />
# ##i##ego sync<br />
}}<br />
<br />
<!--T:19--><br />
This will activate the new 1.2 kits. Now, time to start upgrading:<br />
<br />
<!--T:20--><br />
{{console|body=<br />
# ##i##emerge -u1 gcc<br />
}}<br />
<br />
<!--T:21--><br />
This will upgrade gcc.<br />
<br />
<!--T:22--><br />
This is an ideal time to review the subarch setting of your Funtoo Linux installation. Funtoo Linux 1.2 now has optimizations available for 5th and 6th-generation Intel<br />
Core processors, as well as Ryzen processors. View your current subarch, as well as available subarches, by typing the following command:<br />
<br />
<!--T:23--><br />
{{console|body=<br />
# ##i##ego profile list subarch<br />
<br />
=== ##g##subarch##!g##: === <!--T:24--><br />
<br />
<!--T:25--><br />
amd64-bulldozer, amd64-excavator, amd64-jaguar, amd64-k10<br />
amd64-k8, amd64-k8+sse3, amd64-piledriver, amd64-steamroller<br />
amd64-zen, atom_64, btver1_64, core-avx-i, core2_64, corei7<br />
generic_64, intel64-broadwell, intel64-haswell, intel64-ivybridge<br />
intel64-nehalem, intel64-sandybridge, intel64-silvermont, intel64-skylake<br />
##c##intel64-westmere##!c##*, native_64, nocona, opteron_64, xen-pentium4+sse3_64<br />
<br />
<!--T:26--><br />
#<br />
}}<br />
<br />
<!--T:27--><br />
If desired and supported by your CPU, you can now update your subarch to a more optimized subarch for your hardware. The new subarch profiles available are:<br />
<br />
<!--T:28--><br />
* {{c|intel64-skylake}} - Optimized for Intel Core 6th Generation Processors (see [[intel64-skylake]] for more info.)<br />
* {{c|intel64-broadwell}} - Optimized for Intel Core 5th Generation Processors (see [[intel64-broadwell]] for more info.)<br />
* {{c|amd64-zen}} - Optimized for AMD Ryzen Processors.<br />
<br />
<!--T:29--><br />
Use the {{c|lscpu}} command to view information about your CPU and do a web search for its name to determine what generation CPU it is. Then, the system's subarch<br />
can be changed as follows:<br />
<br />
{{console|body=<br />
# ##i##ego profile subarch intel64-skylake<br />
=== ##g##Enabled Profiles##!g##: === <!--T:30--><br />
<br />
<!--T:31--><br />
##b##arch##!b##: ##c##x86-64bit<br />
##b##build##!b##: ##c##current<br />
##b##subarch##!b##: ##c##intel64-skylake<br />
##b##flavor##!b##: ##c##core<br />
<br />
<!--T:32--><br />
>>> Set subarch to intel64-skylake.<br />
##b##Updating profiles at /etc/portage/make.profile/parent...<br />
<br />
<!--T:33--><br />
#<br />
}}<br />
<br />
<!--T:34--><br />
Now that we have ensured that we have an optimal subarch set for your system, it's time to begin the process of rebuilding critical packages with the new compiler. We will start with glibc. Enter the following command:<br />
<br />
<!--T:35--><br />
{{console|body=<br />
# ##i##emerge -u1 glibc libnsl libtirpc rpcsvc-proto<br />
}}<br />
<br />
<!--T:36--><br />
Glibc and its dependencies/related packages will now be upgraded.<br />
<br />
<!--T:37--><br />
Since moving to 1.2 also includes moving to python-3.6, perform the following steps:<br />
<br />
<!--T:38--><br />
{{console|body=<br />
# ##i##emerge -u1 =dev-lang/python-3.6*<br />
# ##i##emerge -C =dev-lang/python-3.4*<br />
}}<br />
<br />
<!--T:39--><br />
This will ensure that we have python-3.6 ready and installed, and the older python-3.4 removed. Removing python-3.4 is important to ensure that python modules upgrade properly.<br />
<br />
<!--T:40--><br />
Some packages rely on a current ruby being available on the system, and having stale versions on your system can cause problems. To remove these from your system, run:<br />
<br />
<!--T:41--><br />
{{console|body=<br />
# ##i##emerge -C \<=dev-lang/ruby-2.3.0<br />
}}<br />
<br />
<!--T:42--><br />
For upgrading to 1.2, you<br />
have to rebuild all packages, which will ensure that your system is fully optimized with the new gcc.<br />
<br />
<!--T:43--><br />
{{Note|Include the {{c|1=--jobs=3}} (or higher number) option as a parameter to the {{c|emerge}} command if you have sufficient RAM and CPU cores to build several packages in parallel.}}<br />
<br />
<!--T:44--><br />
Here is what you need to run:<br />
<br />
<!--T:45--><br />
{{console|body=<br />
# ##i##emerge --emptytree -a @world<br />
}}<br />
<br />
<!--T:46--><br />
This will fully rebuild all packages on your system. It will take a lot of time, but will ensure everything is freshly rebuilt. Once completed successfully, this will result in an up-to-date system, with potentially better-optimized binaries, benefiting from more recent gcc improvements.<br />
<br />
<!--T:47--><br />
{{Note|If the preceding command fails, you should run 'emerge -uDN1 --keep-going @world' to ensure that all dependencies are fully resolved and rebuilt, then run the 'emerge --emptytree -a @world' command again to ensure that every package is rebuilt with the new gcc compiler.}}<br />
<br />
<!--T:48--><br />
Finally, you will want to either run {{c|etc-update}} or {{c|dispatch-conf}}:<br />
<br />
<!--T:49--><br />
{{console|body=<br />
# ##i##etc-update<br />
}}<br />
<br />
<!--T:50--><br />
If your kernel has been upgraded, make the necessary changes to {{f|/etc/boot.conf}} to make the new kernel the default, and then re-run {{c|ego boot update}}:<br />
<br />
<!--T:51--><br />
{{console|body=<br />
# ##i##ego boot update<br />
}}<br />
<br />
<!--T:52--><br />
Now is a good time to perform a pre-check of any packages that have been installed that may require configuration file updates. One notable example is php-fpm -- you may need to perform the following steps if your system uses php-fpm:<br />
<br />
<!--T:53--><br />
{{console|body=<br />
# ##i##cp /etc/php/fpm-php-7.1/php* /etc/php/fpm-php-7.3/php*<br />
}}<br />
<br />
<!--T:54--><br />
This will ensure that the settings you use for the previously-installed version of php-fpm will be applied to the current version.<br />
<br />
<!--T:55--><br />
{{Note|If you find any other packages that need similar manual steps post-upgrade, please document them here for the benefit of others! Thanks.}}<br />
<br />
<!--T:56--><br />
At this point, the migration to 1.2 should be complete. At a convenient time, reboot your system, and perform a thorough check of all services to ensure they have started<br />
correctly:<br />
<br />
<!--T:57--><br />
{{console|body=<br />
# ##i##reboot<br />
}}<br />
<br />
<!--T:58--><br />
After reboot:<br />
<br />
<!--T:59--><br />
{{console|body=<br />
# ##i##rc-status<br />
}}<br />
<br />
<!--T:60--><br />
Now, perform a final check of any production services to ensure that they are operating properly, by loading web pages, sending test emails, etc.<br />
<br />
<!--T:61--><br />
At this point, you are now upgraded to Funtoo Linux 1.2! Please report any bugs to https://bugs.funtoo.org and let us know of any issues you experience, either as part of the upgrade, related to dependencies, or related to functionality on your upgraded system.<br />
<br />
<!--T:62--><br />
[[Category:Official Documentation]]<br />
</translate></div>Shamus397https://www.funtoo.org/index.php?title=Upgrade_Instructions/1.2-release&diff=23691Upgrade Instructions/1.2-release2018-09-16T14:50:05Z<p>Shamus397: Add help for when --emptytree fails (which is likely), removal of old ruby versions that can cause failures</p>
<hr />
<div>{{Important|The goal of these instructions is to provide Funtoo Linux users with a reliable, consistent set of instructions for upgrading Funtoo Linux from 1.0 to 1.2. Please assist in ensuring that these instructions are complete and guide users through any potential complications. Since this is a wiki, make changes to the page that are needed to make these instructions 100% reliable. Thank you!}}<br />
<br />
These instructions will guide you through the process of upgrading your system from Funtoo Linux 1.0 to 1.2. First, please make sure that you have created a backup of your system. If you choose to proceed without<br />
a backup, then you are assuming the risk of a broken system and dealing with fixing it or re-installing. While these install steps are fairly robust, we will<br />
be removing what appear to be unused packages on the system, and while every precaution is taken to avoid breaking packages, in odd cases this could result in some packages being removed that you actually need. Typically<br />
this will not happen, but since the possibility exists, it is best to be prepared for this possibility, particularly on critical systems.<br />
<br />
Now, edit your {{f|/var/lib/portage/world file.}} Look for catpkgs (ie. "category/packagename") that you no longer use or need on your system and remove them. Also consider packages you may have installed<br />
with {{c|--oneshot}} that are not in the world file but should be, and add them. Portage will use {{f|/var/lib/portage/world}} as the master list of packages that should be on<br />
your system. We will now look into cleaning up any unnecessary packages that are not in the world set. We want to remove these packages for a couple of reasons. First,<br />
they will not get upgraded with a {{c|@world}} update. Second, because they are not included in {{c|@world}}, they could be outdated and have old and problematic dependencies that could hamper our upgrade, since portage will not want to "break" dependencies for these orphaned packages. Third, when we do an {{c|emerge @preserved-rebuild}}, we may end up rebuilding packages that we don't need. So removing unnecessary packages is a good idea for quite a few reasons.<br />
<br />
{{Note|You may be wondering -- what are these packages on my system that are not part of the world set? They could be a number of things. First, they could be build dependencies for certain packages. They could possibly be old slots of packages you already use -- for example, an old version of PHP. The could also be packages that were dependencies of certain packages, but are no longer needed by those packages -- possibly due to changes in {{c|USE}} flags. Often, virtuals are part of this group of packages, and it is generally safe for virtuals to be removed. They will get re-emerged in the future if referenced by an ebuild.}}<br />
<br />
Run the following command and carefully review its output. Do not say "y" at this point:<br />
<br />
{{console|body=<br />
# ##i##emerge -p --depclean --ignore-soname-deps=n | less<br />
}}<br />
<br />
{{Note|The {{c|1=--ignore-soname-deps=n}} option will prevent packages that provide necessary libraries from being removed, even if they appear to be "orphaned." This is an additional safety measure when cleaning dependencies from your system.}}<br />
<br />
Now, review the list of packages that are going to be removed. See anything in this list that you know you need? This would indicate that you need to add the cat/pkg<br />
to {{f|/var/lib/portage/world}} before proceeding. Once the list looks OK, type:<br />
<br />
{{console|body=<br />
# ##i##emerge -a --depclean --ignore-soname-deps=n<br />
}}<br />
<br />
...And type "y" [enter] to remove old packages.<br />
<br />
Now, you should have a still-functioning system, but with all "extra" packages removed. Now it is time to upgrade the packages that remain. <br />
<br />
Now you will want to run {{c|ego sync}} and upgrade to the latest ego-2.4.x series available. <br />
{{console|body=<br />
# ##i## ego sync<br />
# ##i## emerge -v1 ego<br />
}}<br />
<br />
If you have difficulty satisfying deps for it for whatever reason, the following should work:<br />
{{console|body=<br />
# ##i## emerge -v1 --nodeps ego<br />
}}<br />
<br />
If you still cannot merge using emerge, the following should work:<br />
{{console|body=<br />
# ##i## cd /var/git/meta-repo/kits/core-kit/app-admin/ego<br />
# ##i## ebuild ego-2.4.2.ebuild merge<br />
}}<br />
Once the new ego is merged, edit your /etc/ego.conf to look like this:<br />
<br />
{{file|name=/etc/ego.conf|body=<br />
[global]<br />
<br />
release = 1.2<br />
}}<br />
<br />
Now, run the following steps as root.<br />
<br />
{{console|body=<br />
# ##i##ego sync<br />
}}<br />
<br />
This will activate the new 1.2 kits. Now, time to start upgrading:<br />
<br />
{{console|body=<br />
# ##i##emerge -u1 gcc<br />
}}<br />
<br />
This will upgrade gcc.<br />
<br />
This is an ideal time to review the subarch setting of your Funtoo Linux installation. Funtoo Linux 1.2 now has optimizations available for 5th and 6th-generation Intel<br />
Core processors, as well as Ryzen processors. View your current subarch, as well as available subarches, by typing the following command:<br />
<br />
{{console|body=<br />
# ##i##ego profile list subarch<br />
<br />
=== ##g##subarch##!g##: ===<br />
<br />
amd64-bulldozer, amd64-excavator, amd64-jaguar, amd64-k10<br />
amd64-k8, amd64-k8+sse3, amd64-piledriver, amd64-steamroller<br />
amd64-zen, atom_64, btver1_64, core-avx-i, core2_64, corei7<br />
generic_64, intel64-broadwell, intel64-haswell, intel64-ivybridge<br />
intel64-nehalem, intel64-sandybridge, intel64-silvermont, intel64-skylake<br />
##c##intel64-westmere##!c##*, native_64, nocona, opteron_64, xen-pentium4+sse3_64<br />
<br />
#<br />
}}<br />
<br />
If desired and supported by your CPU, you can now update your subarch to a more optimized subarch for your hardware. The new subarch profiles available are:<br />
<br />
* {{c|intel64-skylake}} - Optimized for Intel Core 6th Generation Processors (see [[intel64-skylake]] for more info.)<br />
* {{c|intel64-broadwell}} - Optimized for Intel Core 5th Generation Processors (see [[intel64-broadwell]] for more info.)<br />
* {{c|amd64-zen}} - Optimized for AMD Ryzen Processors.<br />
<br />
Use the {{c|lscpu}} command to view information about your CPU and do a web search for its name to determine what generation CPU it is. Then, the system's subarch<br />
can be changed as follows:<br />
<br />
{{console|body=<br />
# ##i##ego profile subarch intel64-skylake<br />
=== ##g##Enabled Profiles##!g##: ===<br />
<br />
##b##arch##!b##: ##c##x86-64bit<br />
##b##build##!b##: ##c##current<br />
##b##subarch##!b##: ##c##intel64-skylake<br />
##b##flavor##!b##: ##c##core<br />
<br />
>>> Set subarch to intel64-skylake.<br />
##b##Updating profiles at /etc/portage/make.profile/parent...<br />
<br />
#<br />
}}<br />
<br />
Now that we have ensured that we have an optimal subarch set for your system, it's time to begin the process of rebuilding critical packages with the new compiler. We will start with glibc. Enter the following command:<br />
<br />
{{console|body=<br />
# ##i##emerge -u1 glibc libnsl libtirpc rpcsvc-proto<br />
}}<br />
<br />
Glibc and its dependencies/related packages will now be upgraded.<br />
<br />
Since moving to 1.2 also includes moving to python-3.6, perform the following steps:<br />
<br />
{{console|body=<br />
# ##i##emerge -u1 =dev-lang/python-3.6*<br />
# ##i##emerge -C =dev-lang/python-3.4*<br />
}}<br />
<br />
This will ensure that we have python-3.6 ready and installed, and the older python-3.4 removed. Removing python-3.4 is important to ensure that python modules upgrade properly.<br />
<br />
Some packages rely on a current ruby being available on the system, and having stale versions on your system can cause problems. To remove these from your system, run:<br />
<br />
{{console|body=<br />
# ##i##emerge -C \<=dev-lang/ruby-2.3.0<br />
}}<br />
<br />
For upgrading to 1.2, you<br />
have to rebuild all packages, which will ensure that your system is fully optimized with the new gcc.<br />
<br />
{{Note|Include the {{c|1=--jobs=3}} (or higher number) option as a parameter to the {{c|emerge}} command if you have sufficient RAM and CPU cores to build several packages in parallel.}}<br />
<br />
Here is what you need to run:<br />
<br />
{{console|body=<br />
# ##i##emerge --emptytree -a @world<br />
}}<br />
<br />
This will fully rebuild all packages on your system. It will take a lot of time, but will ensure everything is freshly rebuilt. Once completed successfully, this will result in an up-to-date system, with potentially better-optimized binaries, benefiting from more recent gcc improvements.<br />
<br />
{{Note|If the preceding command fails, you should run 'emerge -uDN1 --keep-going @world' to ensure that all dependencies are fully resolved and rebuilt, then run the 'emerge --emptytree -a @world' command again to ensure that every package is rebuilt with the new gcc compiler.}}<br />
<br />
Finally, you will want to either run {{c|etc-update}} or {{c|dispatch-conf}}:<br />
<br />
{{console|body=<br />
# ##i##etc-update<br />
}}<br />
<br />
If your kernel has been upgraded, make the necessary changes to {{f|/etc/boot.conf}} to make the new kernel the default, and then re-run {{c|boot-update}}:<br />
<br />
{{console|body=<br />
# ##i##boot-update<br />
}}<br />
<br />
Now is a good time to perform a pre-check of any packages that have been installed that may require configuration file updates. One notable example is php-fpm -- you may need to perform the following steps if your system uses php-fpm:<br />
<br />
{{console|body=<br />
# ##i##cp /etc/php/fpm-php-7.1/php* /etc/php/fpm-php-7.3/php*<br />
}}<br />
<br />
This will ensure that the settings you use for the previously-installed version of php-fpm will be applied to the current version.<br />
<br />
{{Note|If you find any other packages that need similar manual steps post-upgrade, please document them here for the benefit of others! Thanks.}}<br />
<br />
At this point, the migration to 1.2 should be complete. At a convenient time, reboot your system, and perform a thorough check of all services to ensure they have started<br />
correctly:<br />
<br />
{{console|body=<br />
# ##i##reboot<br />
}}<br />
<br />
After reboot:<br />
<br />
{{console|body=<br />
# ##i##rc-status<br />
}}<br />
<br />
Now, perform a final check of any production services to ensure that they are operating properly, by loading web pages, sending test emails, etc.<br />
<br />
At this point, you are now upgraded to Funtoo Linux 1.2! Please report any bugs to https://bugs.funtoo.org and let us know of any issues you experience, either as part of the upgrade, related to dependencies, or related to functionality on your upgraded system.</div>Shamus397https://www.funtoo.org/index.php?title=Install&diff=19926Install2017-12-11T18:58:25Z<p>Shamus397: Removed spurious "s"</p>
<hr />
<div>{{#widget:AddThis}}<br />
= Install Funtoo Linux = <br />
__NOTITLE__<br />
<languages/><br />
{{Announce|To help us translate this documentation, {{CreateAccount}}, log in to the wiki. Then go to Actions -> Translate in the menu, or click the "Translate this page" link, above. You will be able to select small parts of the install docs and translate these parts to your native language.}}<br />
<translate><br />
== Introduction == <!--T:2--> <br />
<br />
<!--T:3--><br />
This document was written to help you install Funtoo Linux on PC-compatible systems, while keeping distracting options regarding system configuration to a minimum.<br />
<br />
<!--T:4--><br />
If you've had previous experience installing Gentoo Linux then a lot of steps will be familiar, but you should still read through as there are a few differences. If you're new to installing a Gentoo-based Linux, or new to Linux entirely -- welcome! We have attempted to make these installation instructions understandable to new users as well.<br />
<br />
<!--T:5--><br />
{{Note|If you are installing Funtoo Linux on [[Funtoo Linux Installation on ARM|ARM]] architecture, please see [[Funtoo Linux Installation on ARM]] for notable differences regarding ARM support. }}<br />
<br />
== Installation Overview == <!--T:6--> <br />
<br />
<!--T:7--><br />
This is a basic overview of the Funtoo installation process:<br />
<br />
<!--T:8--><br />
# [[#Live CD|Download and boot the live CD of your choice]].<br />
# [[#Prepare Hard Disk|Prepare your disk]].<br />
# [[#Creating filesystems|Create]] and [[#Mounting filesystems|mount]] filesystems.<br />
# [[#Installing the Stage 3 tarball|Install the Funtoo stage tarball]] of your choice.<br />
# [[#Chroot into Funtoo|Chroot into your new system]].<br />
# [[#Downloading the Portage tree|Download the Portage tree]].<br />
# [[#Configuring your system|Configure your system]] and [[#Configuring your network|network]].<br />
# [[#Kernel|Install a kernel]].<br />
# [[#Installing a Bootloader|Install a bootloader]].<br />
# [[#Finishing Steps|Complete final steps]].<br />
# [[#Restart your system|Reboot and enjoy]].<br />
<br />
=== Live CD === <!--T:9--> <br />
<br />
<!--T:10--><br />
In order to install Funtoo Linux, you will first need to boot your computer using a Linux-based Live CD or USB stick. We recommend the Gentoo-based [http://www.sysresccd.org/ System Rescue CD] as it contains lots of tools and utilities and supports both 32-bit and 64-bit systems. It can be burned to CD/DVD or installed on a USB stick. Download it here:<br />
<br />
<!--T:11--><br />
* Download from '''[http://ftp.osuosl.org/pub/funtoo/distfiles/sysresccd/sysresccd-20161103-4.9.0.iso osuosl.org]'''<br />
* Download from '''[http://build.funtoo.org/distfiles/sysresccd/sysresccd-20161103-4.9.0.iso funtoo.org]'''<br />
<br />
<!--T:12--><br />
{{Important|'''NO VIDEO''': We have patched our download of System Rescue CD so that it should initialize video properly when booting from UEFI (See {{bug|FL-2030}}.) If you are using the official, non-Funtoo System Rescue CD, at the GRUB menu, you may need to press {{c|e}} to edit the menu entry and add a GRUB boot line that reads {{c|insmod all_video}} and then boot. This bug has been reported upstream to System Rescue CD developers.}}<br />
<br />
<!--T:237--><br />
{{Note|If using an older version of System Rescue CD, '''be sure to select the <code>rescue64</code> kernel at the boot menu if you are installing a 64-bit system'''. By default, System Rescue CD used to boot in 32-bit mode though the latest version attempts to automatically detect 64-bit processors.}}<br />
<br />
==== Network Access ==== <!--T:13--> <br />
<br />
<!--T:14--><br />
Once you have booted System Rescue CD, see if you have Internet access. Internet access is required for installing Funtoo Linux:<br />
</translate><br />
<br />
<console><br />
# ##i##ping www.google.com<br />
PING www.google.com (216.58.217.36) 56(84) bytes of data.<br />
64 bytes from den03s10-in-f4.1e100.net (216.58.217.36): icmp_seq=1 ttl=57 time=30.1 ms<br />
</console><br />
<br />
<translate><br />
<!--T:15--><br />
If the ping is successful (you see <code>64 bytes</code> messages as above,) then your Network is set up. Hit Control-C to stop the ping. <br />
<br />
<!--T:16--><br />
If you need to set up a WiFi connection for Internet access, then this can be accomplished using the {{c|nmtui}} command-line tool:<br />
</translate><br />
{{console|body=<br />
# ##i##nmtui<br />
}}<br />
<br />
<translate><br />
==== Remote Install ==== <!--T:18--> <br />
<br />
<!--T:19--><br />
Alternatively, you can log into System Rescue CD over the network via SSH to perform the install from another computer, and this may be more convenient way to install Funtoo Linux.<br />
<br />
<!--T:20--><br />
If you'd like to complete the install remotely, here's how. First, you will need to ensure that System Rescue CD has a functioning network connection. Then, you will need to set a root password for System Rescue CD:<br />
</translate><br />
{{console|body=<br />
###i## passwd<br />
New password: ##i##********<br />
Retype new password: ##i##********<br />
passwd: password updated successfully<br />
}}<br />
<translate><br />
<!--T:21--><br />
Once you have typed in a password, you will now need to determine the IP address of System Rescue CD, and then you can use {{c|ssh}} to connect to it. To determine the IP address currently being used by System Rescue CD, type {{c|ifconfig}}:</translate><br />
<br />
{{console|body=<br />
###i## ifconfig<br />
}}<br />
<translate><!--T:238--><br />
Alternatively, determining of an IP address is possible with iproute2 {{c|ip}} tool:</translate><br />
<br />
{{console|body=<br />
###i## ip addr show<br />
}}<br />
<translate><!--T:22--><br />
One of the interfaces should have an IP address (listed as {{c|inet addr:}}) from your LAN. You can then connect remotely, from another system on your LAN, to System Rescue CD, and perform steps from the comfort of an existing OS. On your remote system, type the following, replacing {{c|1.2.3.4}} with the IP address of System Rescue CD. Connecting from an existing Linux or MacOS system would look something like this:</translate><br />
<br />
{{console|body=<br />
(remote system) $ ##i##ssh root@1.2.3.4<br />
Password: ##i##**********}}<br />
<translate><!--T:23--><br />
{{Note|If you'd like to connect remotely from an existing Microsoft Windows system, you'll need to download an SSH client for Windows, such as [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY].}}<br />
<br />
<!--T:24--><br />
After you've logged in via SSH, you're now connected remotely to System Rescue CD and can perform the installation steps.<br />
<br />
=== Prepare Hard Disk === <!--T:25--> <br />
<br />
<!--T:26--><br />
In this section, we'll learn about the different ways that Funtoo Linux can boot from a hard disk. By "boot", we mean the process by which Linux starts after you press the power button on your desktop, laptop or server. You can think of "booting" as a process that starts with your computer's firmware (built-in software) running, and then "finding" the Linux kernel and running it. The Linux kernel then takes over, identifies all your hardware, and starts.<br />
<br />
==== Background ==== <!--T:27--> <br />
<br />
<!--T:28--><br />
{{Note|If you are an absolute beginner to Linux, you may be less confused if you skip to the next section, [[#Which to Use?|Which to Use?]]}}<br />
<br />
<!--T:29--><br />
In earlier times, there was only one way to boot a PC-compatible computer. All of our desktops and servers had standard firmware called the "PC BIOS," all our hard drives used Master Boot Records at the beginning of the disk, where the PC BIOS would "look" to find boot loader code which would in turn load Linux, and our hard drives were partitioned into different regions using the standard MBR partition scheme. That was just how it was done. And we liked it that way!<br />
<br />
<!--T:30--><br />
Then, along came EFI and UEFI, which are new-style firmware designed to boot systems, along with GPT partition tables to define disk partitions on disks larger than 2.2TB. All of the sudden, we had a variety of options for installing and booting Linux systems, turning what once was a one-method-fits-all approach into something a lot more complex.<br />
<br />
<!--T:31--><br />
Let's take a moment to review the options available to you for configuring a hard drive to boot Funtoo Linux. This Install Guide uses, and recommends, the old-school method of BIOS booting and using an MBR. It works and (except for rare cases) is universally supported. There's nothing wrong with it. If your system disk is 2TB or smaller in size, it won't prevent you from using all of your disk's capacity, either.<br />
<br />
<!--T:32--><br />
But, there are some situations where the old-school method isn't optimal. If you have a system disk >2TB in size, then MBR partitions won't allow you to access all your storage. So that's one reason. Another reason is that there are some so-called "PC" systems out there that don't support BIOS booting anymore, and force you to use UEFI to boot. So, out of compassion for people who fall into this predicament, this Install Guide documents UEFI booting too.<br />
<br />
<!--T:33--><br />
Our recommendation is still to go old-school unless you have reason not to. The boot loader we will be using to load the Linux kernel in this guide is called GRUB, so we call this method the '''BIOS + GRUB (MBR)''' method. It's the traditional method of setting up a PC-compatible system to boot Linux.<br />
<br />
<!--T:34--><br />
If you need to use UEFI to boot, we recommend not using the MBR at all for booting, as some systems support this, but others don't. Instead, we recommend using UEFI to boot GRUB, which in turn will load Linux. We refer to this method as the '''UEFI + GRUB (GPT)''' method.<br />
<br />
<!--T:35--><br />
And yes, there are even more methods, some of which are documented on the [[Boot Methods]] page. We used to recommend a '''BIOS + GRUB (GPT)''' method but it is not consistently supported across a wide variety of hardware.<br />
<br />
==== Which to Use? ==== <!--T:36--><br />
<br />
<!--T:37--><br />
'''The big question is -- which boot method should you use?''' Here's how to tell.<br />
<br />
<!--T:38--><br />
;Principle 1 - Old School: If you can reliably boot System Rescue CD and it shows you an initial light blue menu, you are booting the CD using the BIOS, and it's likely that you can thus boot Funtoo Linux using the BIOS. So, go old-school and use BIOS booting, ''unless'' you have some reason to use UEFI, such as having a >2.2TB system disk. In that case, see Principle 2, as your system may also support UEFI booting.<br />
<br />
<!--T:39--><br />
;Principle 2 - New School: If you can reliably boot System Rescue CD and it shows you an initial black and white menu -- congratulations, your system is configured to support UEFI booting. This means that you are ready to install Funtoo Linux to boot via UEFI. Your system may still support BIOS booting, but just be trying UEFI first. You can poke around in your BIOS boot configuration and play with this.<br />
<br />
<!--T:40--><br />
{{Note|'''Advanced Users May Wonder:''' What's the Big Difference between Old School and New School?: Here's the deal. If you go with old-school MBR partitions, your {{f|/boot}} partition will be an ext2 filesystem, and you'll use {{c|fdisk}} to create your MBR partitions. If you go with new-school GPT partitions and UEFI booting, your {{f|/boot}} partition will be a vfat filesystem, because this is what UEFI is able to read, and you will use {{c|gdisk}} to create your GPT partitions. And you'll install GRUB a bit differently. That's about all it comes down to, in case you were curious.}}<br />
<br />
<!--T:41--><br />
To install Funtoo Linux to boot via the New School UEFI method, you must boot System Rescue CD using UEFI. If you successfully boot sysresccd with UEFI, you will see an initial black and white screen to select the mode in which you will boot system rescue cd. Otherwise, if you see a blue screen with black text, UEFI will not be active and you will not be able to set up UEFI booting later in the install process!<br />
<br />
<!--T:42--><br />
{{Note|'''Some motherboards may appear to support UEFI, but don't.''' Do your research. For example, the Award BIOS in my Gigabyte GA-990FXA-UD7 rev 1.1 has an option to enable UEFI boot for CD/DVD. '''This is not sufficient for enabling UEFI boot for hard drives and installing Funtoo Linux.''' UEFI must be supported for both removable media (so you can boot System Rescue CD using UEFI) as well as fixed media (so you can boot your new Funtoo Linux installation.) It turns out that later revisions of this board (rev 3.0) have a new BIOS that fully supports UEFI boot. This may point to a third principle -- know thy hardware.}}<br />
<br />
==== Old-School (BIOS/MBR) Method ==== <!--T:43--> <br />
<br />
<!--T:44--><br />
{{Note|Use this method if you are booting using your BIOS, and if your System Rescue CD initial boot menu was light blue. If you're going to use the new-school method, [[#New-School (UEFI/GPT) Method|click here to jump down to UEFI/GPT.]]}}<br />
<br />
<!--T:46--><br />
First, it's a good idea to make sure that you've found the correct hard disk to partition. Try this command and verify that {{f|/dev/sda}} is the disk that you want to partition:<br />
</translate><br />
{{console|body=<br />
###i## fdisk -l /dev/sda<br />
<br />
Disk /dev/sda: 640.1 GB, 640135028736 bytes, 1250263728 sectors<br />
Units = sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disk label type: gpt<br />
<br />
# Start End Size Type Name<br />
1 2048 1250263694 596.2G Linux filesyste Linux filesystem<br />
}}<br />
<translate><!--T:47--><br />
Now, it is recommended that you erase any existing MBR or GPT partition tables on the disk, which could confuse the system's BIOS at boot time. We accomplish this using {{c|sgdisk}}:<br />
{{Warning|This will make any existing partitions inaccessible! You are '''strongly''' cautioned and advised to backup any critical data before proceeding.}}</translate><br />
<br />
{{console|body=<br />
###i## sgdisk --zap-all /dev/sda<br />
<br />
Creating new GPT entries.<br />
GPT data structures destroyed! You may now partition the disk using fdisk or<br />
other utilities.<br />
}}<br />
<translate><!--T:48--><br />
This output is also nothing to worry about, as the command still succeded:</translate><br />
<br />
{{console|body=<br />
***************************************************************<br />
Found invalid GPT and valid MBR; converting MBR to GPT format<br />
in memory. <br />
***************************************************************<br />
}}<translate><br />
<!--T:50--><br />
Now we will use {{c|fdisk}} to create the MBR partition table and partitions:<br />
</translate><br />
{{console|body=<br />
###i## fdisk /dev/sda<br />
}}<br />
<translate><br />
<!--T:51--><br />
Within {{c|fdisk}}, follow these steps:<br />
<br />
<!--T:52--><br />
'''Empty the partition table''':<br />
</translate><br />
{{console|body=<br />
Command (m for help): ##i##o ↵<br />
}}<br />
<translate><!--T:53--><br />
'''Create Partition 1''' (boot):</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (1-4, default 1): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+128M ↵<br />
}}<br />
<translate><!--T:54--><br />
'''Create Partition 2''' (swap):</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (2-4, default 2): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+2G ↵<br />
Command (m for help): ##i##t ↵ <br />
Partition number (1,2, default 2): ##i## ↵<br />
Hex code (type L to list all codes): ##i##82 ↵<br />
}}<br />
<translate><!--T:55--><br />
'''Create the root partition:'''</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (3,4, default 3): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##↵<br />
}}<br />
<translate><!--T:56--><br />
'''Verify the partition table:'''</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##p<br />
<br />
Disk /dev/sda: 298.1 GiB, 320072933376 bytes, 625142448 sectors<br />
Units: sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disklabel type: dos<br />
Disk identifier: 0x82abc9a6<br />
<br />
Device Boot Start End Blocks Id System<br />
/dev/sda1 2048 264191 131072 83 Linux<br />
/dev/sda2 264192 4458495 2097152 82 Linux swap / Solaris<br />
/dev/sda3 4458496 625142447 310341976 83 Linux<br />
}}<br />
<translate><!--T:57--><br />
'''Write the partition table to disk:'''</translate><br />
<br />
{{console|body=Command (m for help): ##i##w}}<br />
<translate><!--T:58--><br />
Your new MBR partition table will now be written to your system disk.<br />
<br />
<!--T:59--><br />
{{Note|You're done with partitioning! Now, jump over to [[#Creating filesystems|Creating filesystems]].}}<br />
<br />
==== New-School (UEFI/GPT) Method ==== <!--T:60--> <br />
<br />
<!--T:61--><br />
{{Note|Use this method if you are interested in booting using UEFI, and if your System Rescue CD initial boot menu was black and white. If it was light blue, this method will not work.}}<br />
<br />
<!--T:62--><br />
The {{c|gdisk}} commands to create a GPT partition table are as follows. Adapt sizes as necessary, although these defaults will work for most users. Start {{c|gdisk}}:<br />
</translate><br />
{{console|body=###i## gdisk /dev/sda}}<br />
<translate><!--T:63--><br />
Within {{c|gdisk}}, follow these steps:<br />
<br />
<!--T:64--><br />
'''Create a new empty partition table''' (This ''will'' erase all data on the disk when saved):<br />
</translate><br />
{{console|body=<br />
Command: ##i##o ↵<br />
This option deletes all partitions and creates a new protective MBR.<br />
Proceed? (Y/N): ##i##y ↵<br />
}}<br />
<translate><!--T:65--><br />
'''Create Partition 1''' (boot):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##1 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+500M ↵<br />
Hex Code: ##i##EF00 ↵<br />
}}<br />
<translate><!--T:66--><br />
'''Create Partition 2''' (swap):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##2 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+4G ↵<br />
Hex Code: ##i##8200 ↵<br />
}}<br />
<translate><!--T:67--><br />
'''Create Partition 3''' (root):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##3 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##↵##!i## (for rest of disk)<br />
Hex Code: ##i##↵<br />
}}<br />
<translate><!--T:68--><br />
Along the way, you can type "{{c|p}}" and hit Enter to view your current partition table. If you make a mistake, you can type "{{c|d}}" to delete an existing partition that you created. When you are satisfied with your partition setup, type "{{c|w}}" to write your configuration to disk:<br />
<br />
<!--T:69--><br />
'''Write Partition Table To Disk''':<br />
</translate><br />
{{console|body=<br />
Command: ##i##w ↵<br />
Do you want to proceed? (Y/N): ##i##Y ↵<br />
}}<translate><br />
<!--T:70--><br />
The partition table will now be written to the disk and {{c|gdisk}} will close.<br />
<br />
<!--T:71--><br />
Now, your GPT/GUID partitions have been created, and will show up as the following ''block devices'' under Linux:<br />
<br />
<!--T:72--><br />
* {{c|/dev/sda1}}, which will be used to hold the {{c|/boot}} filesystem, <br />
<br />
<!--T:73--><br />
* {{c|/dev/sda2}}, which will be used for swap space, and <br />
<br />
<!--T:74--><br />
* {{c|/dev/sda3}}, which will hold your root filesystem.<br />
<br />
{{Tip|You can verify that the block devices above were correctly created by running the command {{c|lsblk}}.}}<br />
==== Creating filesystems ==== <!--T:75--> <br />
<br />
<!--T:76--><br />
{{Note|This section covers both BIOS ''and'' UEFI installs. Don't skip it!}}<br />
<br />
<!--T:77--><br />
Before your newly-created partitions can be used, the block devices that were created in the previous step need to be initialized with filesystem ''metadata''. This process is known as ''creating a filesystem'' on the block devices. After filesystems are created on the block devices, they can be mounted and used to store files.<br />
<br />
<!--T:78--><br />
Let's keep this simple. Are you using old-school MBR partitions? If so, let's create an ext2 filesystem on {{f|/dev/sda1}}:<br />
</translate><br />
{{console|body=###i## mkfs.ext2 /dev/sda1}}<br />
<translate><!--T:79--><br />
If you're using new-school GPT partitions for UEFI, you'll want to create a vfat filesystem on {{c|/dev/sda1}}, because this is what UEFI is able to read:<br />
</translate><br />
{{console|body=###i## mkfs.vfat -F 32 /dev/sda1}}<br />
<translate><!--T:80--><br />
Now, let's create a swap partition. This partition will be used as disk-based virtual memory for your Funtoo Linux system.<br />
<br />
<!--T:81--><br />
You will not create a filesystem on your swap partition, since it is not used to store files. But it is necessary to initialize it using the {{c|mkswap}} command. Then we'll run the {{c|swapon}} command to make your newly-initialized swap space immediately active within the live CD environment, in case it is needed during the rest of the install process:<br />
</translate><br />
{{console|body=<br />
# ##i##mkswap /dev/sda2<br />
# ##i##swapon /dev/sda2<br />
}}<translate><br />
<!--T:82--><br />
Now, we need to create a root filesystem. This is where Funtoo Linux will live. We generally recommend ext4 or XFS root filesystems. If you're not sure, choose ext4. Here's how to create a root ext4 filesystem:</translate><br />
<br />
{{console|body=###i## mkfs.ext4 /dev/sda3}}<br />
<translate><!--T:83--><br />
...and here's how to create an XFS root filesystem, if you prefer to use XFS instead of ext4:</translate><br />
<br />
{{console|body=###i## mkfs.xfs /dev/sda3}}<br />
<translate><!--T:84--><br />
Your filesystems (and swap) have all now been initialized, so that that can be mounted (attached to your existing directory heirarchy) and used to store files. We are ready to begin installing Funtoo Linux on these brand-new filesystems.<br />
<br />
<!--T:85--><br />
{{Warning|When deploying an OpenVZ host, please use ext4 exclusively. The Parallels development team tests extensively with ext4, and modern versions of {{c|openvz-rhel6-stable}} are '''not''' compatible with XFS, and you may experience kernel bugs.}}<br />
<br />
==== Mounting filesystems ==== <!--T:86--> <br />
<br />
<!--T:87--><br />
Mount the newly-created filesystems as follows, creating {{c|/mnt/funtoo}} as the installation mount point:<br />
</translate><br />
{{console|body=<br />
###i## mkdir /mnt/funtoo<br />
###i## mount /dev/sda3 /mnt/funtoo<br />
###i## mkdir /mnt/funtoo/boot<br />
###i## mount /dev/sda1 /mnt/funtoo/boot<br />
}}<br />
<translate><!--T:88--><br />
Optionally, if you have a separate filesystem for {{f|/home}} or anything else:</translate><br />
<br />
{{console|body=<br />
###i## mkdir /mnt/funtoo/home<br />
###i## mount /dev/sda4 /mnt/funtoo/home<br />
}}<br />
<translate><!--T:89--><br />
If you have {{f|/tmp}} or {{f|/var/tmp}} on a separate filesystem, be sure to change the permissions of the mount point to be globally-writeable after mounting, as follows:</translate><br />
{{console|body=###i## chmod 1777 /mnt/funtoo/tmp}}<translate><br />
<br />
==== Setting the Date ==== <!--T:90--> <br />
<br />
<!--T:91--><br />
{{Important|If your system's date and time are too far off (typically by months or years,) then it may prevent Portage from properly downloading source tarballs. This is because some of our sources are downloaded via HTTPS, which use SSL certificates and are marked with an activation and expiration date. However, if your system time is relatively close to correct, you can probably skip this step for now.}}<br />
<br />
<!--T:92--><br />
Now is a good time to verify the date and time are correctly set to UTC. Use the {{c|date}} command to verify the date and time:<br />
</translate><br />
{{console|body=<br />
###i## date<br />
Fri Jul 15 19:47:18 UTC 2011<br />
}}<br />
<translate><!--T:93--><br />
If the date and/or time need to be corrected, do so using {{c|date MMDDhhmmYYYY}}, keeping in mind {{c|hhmm}} are in 24-hour format. The example below changes the date and time to "July 16th, 2011 @ 8:00PM" UTC:</translate><br />
<br />
{{console|body=<br />
###i## date 071620002011<br />
Fri Jul 16 20:00:00 UTC 2011<br />
}}<br />
<translate><!--T:94--><br />
Once you have set the system clock, it's a very good idea to copy the time to the hardware clock, so it persists across reboots:</translate><br />
<br />
{{console|body=###i## hwclock --systohc}}<br />
<translate><br />
=== Installing the Stage 3 tarball === <!--T:95--> <br />
<br />
<!--T:96--><br />
Now that filesystems are created and your hardware and system clock are set, the next step is downloading the initial Stage 3 tarball. The Stage 3 is a pre-compiled system used as a starting point to install Funtoo Linux. <br />
<br />
<!--T:97--><br />
To download the correct build of Funtoo Linux for your system, head over to the [[Subarches]] page. Subarches are builds of Funtoo Linux that are designed to run on a particular type of CPU, to offer the best possible performance. They also take advantage of the instruction sets available for each CPU.<br />
<br />
If you don't know which subarch to choose, issue this command:<br />
<console><br />
###i## gcc -march=native -Q --help=target | grep march<br />
</console><br />
<br />
<!--T:98--><br />
The [[Subarches]] page lists all CPU-optimized versions of Funtoo Linux. Find the one that is appropriate for the type of CPU that your system has, and then click on its name in the first column (such as {{c|corei7}}, for example.) You will then go to a page dedicated to that subarch, and the stage3s available for download will be listed. If you are using a virtualization technology to run Funtoo Linux, and your VM may migrate to different types of hardware, then it's recommended that you use a stage3 that is optimized for the oldest CPU instruction set that your VM will run on, or a generic image if it may run on both AMD and Intel processors.<br />
<br />
<!--T:99--><br />
For most subarches, you will have several stage3s available to choose from. This next section will help you understand which one to pick.<br />
<br />
==== Which Build? ==== <!--T:100--> <br />
<br />
<!--T:101--><br />
''Pick {{c|funtoo-current}}.'''<br />
<br />
==== Which Variant? ==== <!--T:104--> <br />
<br />
<!--T:105--><br />
If you're not sure, pick {{c|standard}}.<br />
<br />
<!--T:106--><br />
Our "regular" stage3's are listed with a variant of {{c|standard}}. The following variant builds are available:<br />
<br />
<!--T:107--><br />
{{TableStart}}<br />
{{2ColHead|Variant|Description}}<br />
<tr><td>{{c|standard}}</td><td>The "standard" version of Funtoo Linux</td></tr><br />
<tr><td>{{c|pure64}}</td><td>A 64-bit build that drops multilib (32-bit compatibility) support. Can be ideal for server systems.</td></tr><br />
<tr><td>{{c|hardened}}</td><td>Includes PIE/SSP toolchain for enhanced security. PIE does require the use of PaX in the kernel, while SSP works with any kernel, and provides enhanced security in user-space to avoid stack-based exploits. For expert users.</td></tr><br />
{{TableEnd}}<br />
<br />
==== Download the Stage3 ==== <!--T:108--> <br />
<br />
<!--T:109--><br />
Once you have found the stage3 that you would like to download, use {{c|wget}} to download the Stage 3 tarball you have chosen to use as the basis for your new Funtoo Linux system. It should be saved to the {{f|/mnt/funtoo}} directory as follows:<br />
</translate><br />
{{console|body=<br />
###i## cd /mnt/funtoo<br />
###i## wget http://build.funtoo.org/funtoo-current/x86-64bit/generic_64/stage3-latest.tar.xz<br />
}}<br />
<translate><!--T:110--><br />
Note that 64-bit systems can run 32-bit or 64-bit stages, but 32-bit systems can only run 32-bit stages. Make sure that you select a Stage 3 build that is appropriate for your CPU. If you are not certain, it is a safe bet to choose the {{c|generic_64}} or {{c|generic_32}} stage. Consult the [[Subarches]] page for more information.<br />
<br />
<!--T:111--><br />
Once the stage is downloaded, extract the contents with the following command, substituting in the actual name of your Stage 3 tarball:</translate><br />
{{console|body=<br />
###i## tar xpf stage3-latest.tar.xz<br />
}}<translate><br />
<!--T:112--><br />
{{Important|It is very important to use {{c|tar's}} "{{c|'''p'''}}" option when extracting the Stage 3 tarball - it tells {{c|tar}} to ''preserve'' any permissions and ownership that exists within the archive. Without this option, your Funtoo Linux filesystem permissions will be incorrect.}}<br />
<br />
=== Chroot into Funtoo === <!--T:113--><br />
To install Funtoo Linux, the {{c|chroot}} command is first used. The chroot command will "switch into" the new Funtoo Linux system, so the commands you execute after running "chroot" will run within your newly-extracted Funtoo Linux system.<br />
<br />
<!--T:114--><br />
Before chrooting, there are a few things that need to be done to set up the chroot environment. You will need to mount {{f|/proc}}, {{f|/sys}} and {{f|/dev}} inside your new system. Use the following commands to do so:</translate><br />
{{console|body=<br />
# ##i##cd /mnt/funtoo<br />
# ##i##mount -t proc none proc<br />
# ##i##mount --rbind /sys sys<br />
# ##i##mount --rbind /dev dev<br />
}}<translate><br />
<!--T:115--><br />
You'll also want to copy over {{f|resolv.conf}} in order to have proper resolution of Internet hostnames from inside the chroot:</translate><br />
{{console|body=<br />
# ##i##cp /etc/resolv.conf /mnt/funtoo/etc/<br />
}}<translate><br />
<!--T:116--><br />
Now you can chroot into your new system. Use <code>env</code> before <code>chroot</code> to ensure that no environment settings from the installation media are pulled in to your new system:</translate><br />
<br />
{{console|body=###i## env -i HOME=/root TERM=$TERM /bin/chroot . bash -l}}<br />
<translate><!--T:117--><br />
{{Note|For users of live CDs with 64-bit kernels installing 32-bit systems: Some software may use {{c|uname -r}} to check whether the system is 32 or 64-bit. You may want append linux32 to the chroot command as a workaround, but it's generally not needed.}}<br />
{{Important|If you receive the error "{{c|chroot: failed to run command `/bin/bash': Exec format error}}", it is most likely because you are running a 32-bit kernel and trying to execute 64-bit code. Make sure that you have selected the proper type of kernel when booting SystemRescueCD.}}<br />
<br />
<!--T:118--><br />
It's also a good idea to change the default command prompt while inside the chroot. This will avoid confusion if you have to change terminals. Use this command:<br />
{{console|body=# ##i##export PS1="(chroot) $PS1"}}<br />
Test internet name resolution from within the chroot:<br />
{{console|body=###i## ping -c 5 google.com}}<br />
If you can't ping, make sure {{f|/etc/resolv.conf}} doesn't contain things like {{c|127.0.x.x}} addresses, if it does, change the {{c|127.0.x.x}} entry to {{c|8.8.8.8}} -- Google's public dns address. Make sure to replace this with your dns of choice once the system is installed.<br />
<br />
<br />
Congratulations! You are now chrooted inside a Funtoo Linux system. Now it's time to get Funtoo Linux properly configured so that Funtoo Linux will start successfully, without any manual assistance, when your system is restarted.<br />
<br />
=== Downloading the Portage tree === <!--T:120--> <br />
<br />
Now it's time to install a copy of the Portage repository, which contains package scripts (ebuilds) that tell portage how to build and install thousands of different software packages. To create the Portage repository, simply run {{c|ego sync}} from within the chroot. This will automatically clone the portage tree from [https://github.com/funtoo/meta-repo GitHub] and all kit submodules:<br />
<br />
{{console|body=<br />
(chroot) ###i## cd /var/tmp<br />
(chroot) ###i## ego sync<br />
}}<br />
<br />
{{Note|The {{c|cd /var/tmp}} command works around a bug that is fixed in ego-2.3.0.}}<br />
<br />
=== Configuring your system === <!--T:123--><br />
As is expected from a Linux distribution, Funtoo Linux has its share of configuration files. The one file you are absolutely required to edit in order to ensure that Funtoo Linux boots successfully is {{f|/etc/fstab}}. The others are optional. <br />
<br />
==== Using Nano ==== <!--T:124--> <br />
<br />
<!--T:125--><br />
The default editor included in the chroot environment is called {{c|nano}}. To edit one of the files below, run nano as follows:<br />
<br />
<!--T:126--><br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/fstab<br />
}}<br />
When in the editor, you can use arrow keys to move the cursor, and common keys like backspace and delete will work as expected. To save the file, press Control-X, and answer {{c|y}} when prompted to save the modified buffer if you would like to save your changes.<br />
<br />
==== Configuration Files ==== <!--T:127--> <br />
<br />
<!--T:128--><br />
Here are a full list of files that you may want to edit, depending on your needs:<br />
{{TableStart}}<br />
{{3ColHead|File|Do I need to change it?|Description}}<br />
<tr class="danger"><br />
<td>{{c|/etc/fstab}}</td><br />
<td>'''YES - required'''</td><br />
<td>Mount points for all filesystems to be used at boot time. This file must reflect your disk partition setup. We'll guide you through modifying this file below.</td><br />
</tr><tr><br />
<td>{{c|/etc/localtime}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Your timezone, which will default to UTC if not set. This should be a symbolic link to something located under /usr/share/zoneinfo (e.g. /usr/share/zoneinfo/America/Montreal) </td><br />
</tr><tr><br />
<td>{{c|/etc/portage/make.conf}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Parameters used by gcc (compiler), portage, and make. ''Note that it is normal for this file to be empty in Funtoo Linux, as many settings have been migrated to our enhanced profile system.''</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/hostname}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Used to set system hostname. Set the {{c|hostname}} variable to the fully-qualified (with dots, ie. {{c|foo.funtoo.org}}) name if you have one. Otherwise, set to the local system hostname (without dots, ie. {{c|foo}}). Defaults to {{c|localhost}} if not set.</td><br />
</tr><tr><br />
<td>{{c|/etc/hosts}}</td><br />
<td>''No''</td><br />
<td> You no longer need to manually set the hostname in this file. This file is automatically generated by {{c|/etc/init.d/hostname}}.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/keymaps}}</td><br />
<td>Optional</td><br />
<td>Keyboard mapping configuration file (for console pseudo-terminals). Set if you have a non-US keyboard. See [[Funtoo Linux Localization]].</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/hwclock}}</td><br />
<td>Optional</td><br />
<td>How the time of the battery-backed hardware clock of the system is interpreted (UTC or local time). Linux uses the battery-backed hardware clock to initialize the system clock when the system is booted.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/modules}}</td><br />
<td>Optional</td><br />
<td>Kernel modules to load automatically at system startup. Typically not required. See [[Additional Kernel Resources]] for more info.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/consolefont}}</td><br />
<td>Optional</td><br />
<td>Allows you to specify the default console font. To apply this font, enable the consolefont service by running rc-update add consolefont.</td><br />
</tr><tr><br />
<td>{{c|profiles}}</td><br />
<td>Optional</td><br />
<td>Some useful portage settings that may help speed up intial configuration.</td><br />
</tr><br />
{{TableEnd}}<br />
<br />
<!--T:129--><br />
If you're installing an English version of Funtoo Linux, you're in luck, as most of the configuration files can be used as-is. If you're installing for another locale, don't worry. We will walk you through the necessary configuration steps on the [[Funtoo Linux Localization]] page, and if needed, there's always plenty of friendly, helpful support available. (See [[Getting Help]])<br />
<br />
<!--T:130--><br />
Let's go ahead and see what we have to do. Use {{c|nano -w <name_of_file>}} to edit files -- the "{{c|-w}}" argument disables word-wrapping, which is handy when editing configuration files. You can copy and paste from the examples.<br />
<br />
<!--T:131--><br />
{{Warning|It's important to edit your {{c|/etc/fstab}} file before you reboot! You will need to modify both the "fs" and "type" columns to match the settings for your partitions and filesystems that you created with {{c|gdisk}} or {{c|fdisk}}. Skipping this step may prevent Funtoo Linux from booting successfully.}}<br />
<br />
==== /etc/fstab ==== <!--T:132--><br />
<br />
<!--T:133--><br />
{{f|/etc/fstab}} is used by the {{c|mount}} command which is run when your system boots. Lines in this file inform {{c|mount}} about filesystems to be mounted and how they should be mounted. In order for the system to boot properly, you must edit {{f|/etc/fstab}} and ensure that it reflects the partition configuration you used earlier in the install process. If you can't remember the partition configuration that you used earlier, the {{c|lsblk}} command may be of help to you:<br />
</translate><br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/fstab<br />
}}<br />
{{file|name=/etc/fstab|desc=An example fstab file|body=<br />
# The root filesystem should have a pass number of either 0 or 1.<br />
# All other filesystems should have a pass number of 0 or greater than 1.<br />
#<br />
# NOTE: If your BOOT partition is ReiserFS, add the notail option to opts.<br />
#<br />
# See the manpage fstab(5) for more information.<br />
#<br />
# <fs> <mountpoint> <type> <opts> <dump/pass><br />
<br />
/dev/sda1 /boot ext2 noauto,noatime 1 2<br />
/dev/sda2 none swap sw 0 0<br />
/dev/sda3 / ext4 noatime 0 1<br />
#/dev/cdrom /mnt/cdrom auto noauto,ro 0 0<br />
}}<br />
<translate><br />
<!--T:135--><br />
{{Note|If you're using UEFI to boot, change the {{f|/dev/sda1}} line so that it says {{c|vfat}} instead of {{c|ext2}}. Similarly, make sure that the {{f|/dev/sda3}} line specifies either {{c|xfs}} or {{c|ext4}}, depending on which filesystem you chose earlier on in the installation process when you created filesystems.}}<br />
<br />
==== /etc/localtime ==== <!--T:136--> <br />
<br />
<!--T:137--><br />
{{f|/etc/localtime}} is used to specify the timezone that your machine is in, and defaults to UTC. If you would like your Funtoo Linux system to use local time, you should replace {{f|/etc/localtime}} with a symbolic link to the timezone that you wish to use. <br />
<br />
<!--T:138--><br />
{{console|body=<br />
(chroot) ###i## ln -sf /usr/share/zoneinfo/MST7MDT /etc/localtime<br />
}}<br />
The above sets the timezone to Mountain Standard Time (with daylight savings). Type {{c|ls /usr/share/zoneinfo}} to list available timezones. There are also sub-directories containing timezones described by location.<br />
<br />
==== /etc/portage/make.conf ==== <!--T:139--> <br />
<br />
<!--T:140--><br />
{{c|USE}} flags define what functionality is enabled when packages are built. It is not recommended to add a lot of USE flags during installation; you should wait until you have a working, bootable system before changing your USE flags. A USE flag prefixed with a minus ("{{c|-}}") sign tells Portage not to use the flag when compiling. A Funtoo guide to USE flags will be available in the future. For now, you can find out more information about USE flags in the [https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/USE Gentoo Handbook].<br />
<br />
==== /etc/conf.d/hwclock ==== <!--T:147--><br />
If you dual-boot with Windows, you'll need to edit this file and change the value of '''clock''' from '''UTC''' to '''local''', because Windows will set your hardware clock to local time every time you boot Windows. Otherwise you normally wouldn't need to edit this file.<br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/conf.d/hwclock<br />
}}<br />
==== Localization ====<br />
<br />
<!--T:148--><br />
By default, Funtoo Linux is configured with Unicode (UTF-8) enabled, and for the US English locale and keyboard. If you would like to configure your system to use a non-English locale or keyboard, see [[Funtoo Linux Localization]].<br />
<br />
=== Introducing Portage === <!--T:149--> <br />
<br />
<!--T:150--><br />
Portage, the Funtoo Linux package manager has a command called <code>emerge</code> which is used to build and install packages from source. It also takes care of installing all of the package's dependencies. You call emerge like this:<br />
<br />
<!--T:151--><br />
<console><br />
(chroot) # ##i##emerge packagename<br />
</console><br />
<br />
<!--T:152--><br />
When you install a package by specifying its name in the command-line, Portage records its name in the <code>/var/lib/portage/world</code> file. It does so because it assumes that, since you have installed it by name, you want to consider it part of your system and want to keep the package updated in the future. This is a handy feature, since when packages are being added to the <code>world</code> set, we can update our entire system by typing:<br />
<br />
<!--T:153--><br />
<console><br />
(chroot) # ##i##ego sync<br />
(chroot) # ##i##emerge -auDN @world<br />
</console><br />
<br />
<!--T:154--><br />
This is the "official" way to update your Funtoo Linux system. Above, we first update our Portage tree using git to grab the latest ebuilds (scripts), and then run an emerge command to update the <code>world</code> set of packages. The options specified tell <code>emerge</code> to:<br />
<br />
<!--T:155--><br />
* '''<code>a</code>''' - show us what will be emerged, and '''ask''' us if we want to proceed<br />
* '''<code>u</code>''' - '''update''' the packages we specify -- don't emerge them again if they are already emerged.<br />
* '''<code>D</code>''' - Consider the entire dependency tree of packages when looking for updates. In other words, do a '''deep''' update.<br />
* '''<code>N</code>''' - Update any packages that have changed ('''new''') USE settings.<br />
<br />
<!--T:156--><br />
You should also consider passing <code>--with-bdeps=y</code> when emerging @world, at least once in a while. This will update build dependencies as well.<br />
<br />
<!--T:157--><br />
Of course, sometimes we want to install a package but not add it to the <code>world</code> file. This is often done because you only want the package installed temporarily or because you know the package in question is a dependency of another package. If this behavior is desired, you call emerge like this:<br />
<br />
<!--T:158--><br />
<console><br />
(chroot) # ##i##emerge -1 packagename<br />
</console><br />
<br />
<!--T:159--><br />
Advanced users may be interested in the [[Emerge]] wiki page.<br />
<br />
==== Updating World ==== <!--T:160--> <br />
<br />
<!--T:161--><br />
Certain packages in the Funtoo stage3 tarball are compiled with the bindist USE flag enabled. You may notice a dependency resolution problem with bindist USE during updating packages after initial system setup. To avoid potential problems, update the system before first boot as shown below:<br />
<br />
<!--T:162--><br />
<console><br />
(chroot) # ##i##ego sync<br />
(chroot) # ##i##emerge -auDN @world<br />
</console><br />
<br />
<!--T:163--><br />
{{fancyimportant|1=<br />
Make sure you read any post emerge messages and follow their instructions. This is especially true if you have upgraded perl or python.}}<br />
<br />
=== Kernel === <!--T:164--> <br />
<br />
<!--T:165--><br />
Starting mid-May 2015, Funtoo Linux stage3's include a pre-built {{c|debian-sources}} kernel to make installation faster and easier. To see if debian-sources is installed, type:<br />
</translate><br />
{{console|body=<br />
(chroot) # ##i##emerge -s debian-sources<br />
Searching... <br />
[ Results for search key : ##b##debian-sources##!b## ]<br />
[ Applications found : ##b##1##!b## ]<br />
<br />
* ##b##sys-kernel/debian-sources##!b##<br />
##g##Latest version available:##!g## 3.19.3<br />
##g##Latest version installed:##!g## 3.19.3<br />
##g##Size of files:##!g## 81,292 kB<br />
##g##Homepage:##!g## http://www.debian.org<br />
##g##Description:##!g## Debian Sources (and optional binary kernel)<br />
##g##License:##!g## GPL-2<br />
}}<br />
<translate><br />
<!--T:166--><br />
If a version is listed under {{c|Latest version installed}}, then debian-sources is already pre-built for you and you can skip the rest of the Kernel section, and proceed to the [[#Installing a Bootloader|Installing a Bootloader section]].<br />
<br />
==== Building the Kernel ==== <!--T:167--> <br />
<br />
<!--T:168--><br />
If you need to build a kernel for Funtoo Linux, please follow these steps:<br />
<br />
<!--T:169--><br />
{{Fancynote|1=<br />
See [[Funtoo Linux Kernels]] for a full list of kernels supported in Funtoo Linux. We recommend <code>debian-sources</code> for new users.}}<br />
<br />
<!--T:170--><br />
{{fancyimportant|1=<br />
<code>debian-sources</code> with <code>binary</code> USE flag requires at least 20GB free in <code>/var/tmp</code> and takes around 1 hour to build on a Intel Core i7 Processor.}}<br />
<br />
<!--T:171--><br />
Let's emerge our kernel:<br />
<br />
<!--T:172--><br />
<console><br />
(chroot) # ##i##emerge debian-sources<br />
</console><br />
<br />
<!--T:173--><br />
Once <code>emerge</code> completes, you'll have a brand new kernel and initramfs installed to <code>/boot</code>, plus kernel headers installed in <code>/usr/src/linux</code>, and you'll be ready to configure the boot loader to load these to boot your Funtoo Linux system.<br />
<br />
<!--T:174--><br />
{{warning|If you have a RAID in your machine, the kernel installation will pull in the <code>mdadm</code> tool as a dependency. It is important to edit the <code>/etc/mdadm.conf</code> file prior to rebooting the machine so the RAID is properly recognised and set up before the kernel attempts to mount it in the tree. Failing to do so can result in an unusable or even unbootable system! For specific details, consult the mdadm man page <code>man mdadm</code> or the [[Package:Mdadm|mdadm]] ebuild page.}}<br />
<br />
<!--T:175--><br />
{{fancynote|NVIDIA card users: the <code>binary</code> USE flag installs the Nouveau drivers which cannot be loaded at the same time as the proprietary drivers, and cannot be unloaded at runtime because of KMS. You need to blacklist it under <code>/etc/modprobe.d/</code>.}}<br />
<br />
<!--T:176--><br />
{{fancynote|For an overview of other kernel options for Funtoo Linux, see [[Funtoo Linux Kernels]]. There may be modules that the Debian kernel doesn't include, a situation where [http://www.funtoo.org/wiki/Funtoo_Linux_Kernels#Using_Debian-Sources_with_Genkernel genkernel] would be useful. Also be sure to see [[:Category:Hardware Compatibility|hardware compatibility]] information.}}<br />
<br />
=== Installing a Bootloader === <!--T:177--><br />
<br />
<!--T:178--><br />
These install instructions show you how to use GRUB to boot using BIOS (old-school) or UEFI (new-school). As of boot-update-1.7.2, now in Portage, the steps are very similar.<br />
<br />
<!--T:179--><br />
First, emerge <code>boot-update</code>. This will also cause <code>grub-2</code> and {{c|efibootmgr}} to be merged, since they are dependencies:<br />
<br />
<!--T:180--><br />
<console><br />
(chroot) # ##i##emerge boot-update<br />
</console><br />
<br />
<!--T:181--><br />
Then, edit <code>/etc/boot.conf</code> using {{c|nano}} and specify "<code>Funtoo Linux genkernel</code>" as the <code>default</code> setting at the top of the file, replacing <code>"Funtoo Linux"</code>. Also, if you're not using memtest86+ remove the entry in boot.conf to avoid errors.<br />
<br />
<!--T:182--><br />
<code>/etc/boot.conf</code> should now look like this:<br />
</translate><br />
{{file|name=/etc/boot.conf|body=<br />
boot {<br />
generate grub<br />
default "Funtoo Linux genkernel" <br />
timeout 3 <br />
}<br />
<br />
"Funtoo Linux" {<br />
kernel bzImage[-v]<br />
}<br />
<br />
"Funtoo Linux genkernel" {<br />
kernel kernel[-v]<br />
initrd initramfs[-v]<br />
params += real_root=auto <br />
} <br />
<br />
"Funtoo Linux better-initramfs" {<br />
kernel vmlinuz[-v]<br />
initrd /initramfs.cpio.gz<br />
}<br />
}}<br />
<translate><br />
<!--T:183--><br />
If you are booting a custom or non-default kernel, please read <code>man boot.conf</code> for information on the various options available to you.<br />
<br />
==== Old School (BIOS) MBR ==== <!--T:184--> <br />
<br />
<!--T:185--><br />
When using "old school" BIOS booting, run the following command to install GRUB to your MBR, and generate the {{c|/boot/grub/grub.cfg}} configuration file that GRUB will use for booting:<br />
<br />
<!--T:186--><br />
<console><br />
(chroot) # ##i##grub-install --target=i386-pc --no-floppy /dev/sda<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
==== New School (UEFI) Boot Entry ==== <!--T:187--><br />
<br />
<!--T:188--><br />
If you're using "new school" UEFI booting, run of the following sets of commands, depending on whether you are installing a 64-bit or 32-bit system. This will add GRUB as a UEFI boot entry.<br />
<br />
<!--T:189--><br />
For x86-64bit systems:<br />
<br />
<!--T:190--><br />
<console><br />
(chroot) # ##i##grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
<!--T:191--><br />
For x86-32bit systems:<br />
<br />
<!--T:192--><br />
<console><br />
(chroot) # ##i##grub-install --target=i386-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
==== First Boot, and in the future... ==== <!--T:193--> <br />
<br />
<!--T:194--><br />
OK -- you are almost ready to boot! <br />
<br />
<!--T:195--><br />
You only need to run <code>grub-install</code> when you first install Funtoo Linux, but you need to re-run <code>boot-update</code> every time you modify your <code>/etc/boot.conf</code> file or add new kernels to your system. This will regenerate {{c|/boot/grub/grub.cfg}} so that you will have new kernels available in your GRUB boot menu, the next time you reboot.<br />
<br />
=== Configuring your network === <!--T:196--> <br />
<br />
<!--T:197--><br />
It's important to ensure that you will be able to connect to your local-area network after you reboot into Funtoo Linux. There are three approaches you can use for configuring your network: NetworkManager, dhcpcd, and the [[Funtoo Linux Networking]] scripts. Here's how to choose which one to use based on the type of network you want to set up.<br />
<br />
==== Wi-Fi ==== <!--T:198--><br />
<br />
<!--T:232--><br />
For laptop/mobile systems where you will be using Wi-Fi, roaming, and connecting to various networks NetworkManager is strongly recommended. <br />
Since Wi-Fi cards require firmware to operate, it is also recommended that you emerge the linux-firmware ebuild:<br />
<br />
<!--T:233--><br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager<br />
}}<br />
<br />
Depending on your architecture, you might now see a message similar to the following:<br />
<br />
{{console|body=<br />
The following USE changes are necessary to proceed<br />
...<br />
}}<br />
This means that your USE flags need to be updated to allow this installation. For now, you can let portage handle this for you by adding the flag <code>--autounmask-write</code>:<br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager --autounmask-write<br />
}}<br />
After this, update the config:<br />
{{console|body=(chroot) # ##i##dispatch-conf<br />
}}<br />
Accept the new config by pressing <code>u</code>. Then, you can proceed to install NetworkManager:<br />
<br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager<br />
(chroot) ###i## rc-update add NetworkManager default<br />
}}<br />
The above command will ensure that NetworkManager starts after you boot into Funtoo Linux. Once you've completed these installation steps and have booted into Funtoo Linux, you can use the {{c|nmtui}} command (which has an easy-to-use console-based interface) to configure NetworkManager so that it will connect (and automatically reconnect, after reboot) to a Wi-Fi access point:<br />
{{console|body=# ##i##nmtui}}<br />
For more information about NetworkManager, see the [[Package:NetworkManager|NetworkManager package page]].<br />
<br />
<!--T:234--><br />
{{Note|wpa_supplicant is also a good choice for wireless network connections. See the {{package|net-wireless/wpa_supplicant}} package for steps involved in setting up wpa_supplicant.}}<br />
<br />
==== Desktop (Wired DHCP) ==== <!--T:200--> <br />
<br />
<!--T:201--><br />
For a home desktop or workstation with wired Ethernet that will use DHCP, the simplest and most effective option to enable network connectivity is to simply add {{c|dhcpcd}} to the default runlevel:<br />
<br />
<!--T:203--><br />
{{console|body=<br />
(chroot) # ##i##rc-update add dhcpcd default}}<br />
When you reboot, {{c|dhcpcd}} will run in the background and manage all network interfaces and use DHCP to acquire network addresses from a DHCP server.<br />
<br />
<!--T:204--><br />
If your upstream DHCP server is dnsmasq, it can be configured to assign addresses via mac address to make servers on DHCP feasible.<br />
<br />
==== Server (Static IP) ==== <!--T:205--><br />
<br />
<!--T:235--><br />
For servers, the [[Funtoo Linux Networking]] scripts are recommended. They are optimized for static configurations and things like virtual ethernet bridging for virtualization setups. See [[Funtoo Linux Networking]] for information on how to use Funtoo Linux's template-based network configuration system.<br />
<br />
==== Hostname ==== <!--T:207--><br />
By default Funtoo uses "localhost" as hostname. Although the system will work perfectly fine using this name, some ebuilds refuse to install when detecting localhost as hostname. It also may create confusion if several systems use the same hostname. Therefore, it is advised to change it to a more meaningful name. The hostname itself is arbitrary, meaning you can choose almost any combination of characters, as long as it makes sense to the system administrator. To change the hostname, edit<br />
<br />
<!--T:208--><br />
{{console|body=<br />
(chroot) # ##i##nano /etc/conf.d/hostname<br />
}}<br />
<br />
<!--T:209--><br />
Look for the line starting with hostname and change the entry between the quotes. Save the file, on the next boot Funtoo will use the new hostname.<br />
<br />
<!--T:210--><br />
{{warning|Do not use special characters in the hostname, as the shell may interpret these, leading to unpredictable results. Use the Latin alphabet: a-z, A-Z, 0-9}}<br />
{{tip|Use short hostnames (up to 8 or 10 characters) to prevent the terminal screen being filled with the hostname, leaving little space for the command itself. This become particularly poignant when coding long command strings in various programming languages like Bash, Python, SQL and Perl}}<br />
<br />
=== Finishing Steps === <!--T:211--><br />
==== Set your root password ==== <br />
It's imperative that you set your root password before rebooting so that you can log in.<br />
<console><br />
(chroot) # ##i##passwd<br />
</console><br />
<br />
===Restart your system === <!--T:212--> <br />
<br />
<!--T:213--><br />
Now is the time to leave chroot, to unmount Funtoo Linux partitions and files and to restart your computer. When you restart, the GRUB boot loader will start, load the Linux kernel and initramfs, and your system will begin booting.<br />
<br />
<!--T:214--><br />
Leave the chroot, change directory to /mnt, unmount your Funtoo partitions, and reboot.<br />
<console><br />
(chroot) # ##i##exit<br />
# ##i##cd /mnt<br />
# ##i##umount -lR funtoo<br />
# ##i##reboot<br />
</console><br />
<br />
<!--T:215--><br />
{{fancynote|System Rescue CD will gracefully unmount your new Funtoo filesystems as part of its normal shutdown sequence.}}<br />
<br />
<!--T:216--><br />
You should now see your system reboot, the GRUB boot loader appear for a few seconds, and then see the Linux kernel and initramfs loading. After this, you should see Funtoo Linux itself start to boot, and you should be greeted with a <code>login:</code> prompt. Funtoo Linux has been successfully installed!<br />
<br />
=== Profiles === <!--T:217--> <br />
<br />
<!--T:218--><br />
Once you have rebooted into Funtoo Linux, you can further customize your system to your needs by using [[Funtoo Profiles]]. A quick introduction to profiles is included below -- consult the [[Funtoo Profiles]] page for more detailed information. There are five basic profile types: arch, build, subarch, flavors and mix-ins:<br />
<br />
<!--T:220--><br />
{{TableStart}}<br />
{{2ColHead|Sub-Profile Type|Description}}<br />
{{2Col|{{c|arch}}|Typically {{c|x86-32bit}} or {{c|x86-64bit}}, this defines the processor type and support of your system. This is defined when your stage was built and should not be changed.}}<br />
{{2Col|{{c|build}}|Defines whether your system is a {{c|current}}, {{c|stable}} or {{c|experimental}} build. {{c|current}} systems will have newer packages unmasked than {{c|stable}} systems. This is defined when your stage is built and is typically not changed.}}<br />
{{2Col|{{c|subarch}}|Defines CPU optimizations for your system. The subarch is set at the time the stage3 is built, but can be changed later to better settings if necessary. Be sure to pick a setting that is compatible with your CPU.}}<br />
{{2Col|{{c|flavor}}|Defines the general type of system, such as {{c|server}} or {{c|desktop}}, and will set default USE flags appropriate for your needs.}}<br />
{{2Col|{{c|mix-ins}}|Defines various optional settings that you may be interested in enabling.}}<br />
{{TableEnd}}<br />
<br />
<!--T:221--><br />
One arch, build and flavor must be set for each Funtoo Linux system, while mix-ins are optional and you can enable more than one if desired. Often, flavors and mix-ins inherit settings from other sub-profiles. Use {{c|epro show}} to view your current profile settings, in addition to any inheritance information:</translate><br />
{{console|body=<br />
(chroot) # ##i## epro show<br />
<br />
=== ##g##Enabled Profiles##!g##: ===<br />
<br />
arch: ##c## x86-64bit<br />
build: ##c## current<br />
subarch: ##c## intel64-haswell<br />
flavor: ##c## desktop<br />
mix-ins: ##c## gnome<br />
<br />
<br />
=== ##g##All inherited flavors from desktop flavor##!g##: ===<br />
<br />
##c##workstation##!c## (from desktop flavor)<br />
##c##core##!c## (from workstation flavor)<br />
##c##minimal##!c## (from core flavor)<br />
<br />
=== ##g##All inherited mix-ins from desktop flavor##!g##: ===<br />
<br />
##c##X##!c## (from workstation flavor)<br />
##c##audio##!c## (from workstation flavor)<br />
##c##dvd##!c## (from workstation flavor)<br />
##c##media##!c## (from workstation flavor)<br />
##c##mediadevice-audio-consumer##!c## (from media mix-in)<br />
##c##mediadevice-base##!c## (from mediadevice-audio-consumer mix-in)<br />
##c##mediadevice-video-consumer##!c## (from media mix-in)<br />
##c##mediadevice-base##!c## (from mediadevice-video-consumer mix-in)<br />
##c##mediaformat-audio-common##!c## (from media mix-in)<br />
##c##mediaformat-gfx-common##!c## (from media mix-in)<br />
##c##mediaformat-video-common##!c## (from media mix-in)<br />
##c##console-extras##!c## (from workstation flavor)<br />
##c##print##!c## (from desktop flavor)<br />
}}<br />
<translate><br />
<!--T:223--><br />
Here are some basic examples of {{c|epro}} usage:<br />
{{TableStart}}<br />
{{2ColHead|Description|Command}}<br />
{{2Col|View available profiles. Enabled profiles will be highlighted in cyan. Directly enabled profiles will be in bold and have a {{c|*}} appended.|{{c|epro list}}}}<br />
{{2Col|Change the system flavor.|{{c|epro flavor desktop}}}}<br />
{{2Col|Add a mix-in.|{{c|epro mix-in +gnome}}}}<br />
{{TableEnd}}<br />
<br />
===Next Steps=== <!--T:228--> <br />
<br />
<!--T:229--><br />
If you are brand new to Funtoo Linux and Gentoo Linux, please check out [[Funtoo Linux First Steps]], which will help get you acquainted with your new system. We also have a category for our [[:Category:Official Documentation|official documentation]], which includes all docs that we officially maintain for installation and operation of Funtoo Linux.<br />
<br />
<!--T:230--><br />
We also have a number of pages dedicated to setting up your system. See [[:Category:First Steps|First Steps]] for a list of these pages.<br />
<br />
<!--T:231--><br />
If your system did not boot correctly, see [[Installation Troubleshooting]] for steps you can take to resolve the problem.<br />
<br />
[[Category:HOWTO]]<br />
[[Category:Install]]<br />
[[Category:Official Documentation]]<br />
</translate></div>Shamus397https://www.funtoo.org/index.php?title=Install&diff=19921Install2017-12-11T18:05:40Z<p>Shamus397: Change language of update being optional to update being mandatory.</p>
<hr />
<div>{{#widget:AddThis}}<br />
= Install Funtoo Linux = <br />
__NOTITLE__<br />
<languages/><br />
{{Announce|To help us translate this documentation, {{CreateAccount}}, log in to the wiki. Then go to Actions -> Translate in the menu, or click the "Translate this page" link, above. You will be able to select small parts of the install docs and translate these parts to your native language.}}<br />
<translate><br />
== Introduction == <!--T:2--> <br />
<br />
<!--T:3--><br />
This document was written to help you install Funtoo Linux on PC-compatible systems, while keeping distracting options regarding system configuration to a minimum.<br />
<br />
<!--T:4--><br />
If you've had previous experience installing Gentoo Linux then a lot of steps will be familiar, but you should still read through as there are a few differences. If you're new to installing a Gentoo-based Linux, or new to Linux entirely -- welcome! We have attempted to make these installation instructions understandable to new users as well.<br />
<br />
<!--T:5--><br />
{{Note|If you are installing Funtoo Linux on [[Funtoo Linux Installation on ARM|ARM]] architecture, please see [[Funtoo Linux Installation on ARM]] for notable differences regarding ARM support. }}<br />
<br />
== Installation Overview == <!--T:6--> <br />
<br />
<!--T:7--><br />
This is a basic overview of the Funtoo installation process:<br />
<br />
<!--T:8--><br />
# [[#Live CD|Download and boot the live CD of your choice]].<br />
# [[#Prepare Hard Disk|Prepare your disk]].<br />
# [[#Creating filesystems|Create]] and [[#Mounting filesystems|mount]] filesystems.<br />
# [[#Installing the Stage 3 tarball|Install the Funtoo stage tarball]] of your choice.<br />
# [[#Chroot into Funtoo|Chroot into your new system]].<br />
# [[#Downloading the Portage tree|Download the Portage tree]].<br />
# [[#Configuring your system|Configure your system]] and [[#Configuring your network|network]].<br />
# [[#Kernel|Install a kernel]].<br />
# [[#Installing a Bootloader|Install a bootloader]].<br />
# [[#Finishing Steps|Complete final steps]].<br />
# [[#Restart your system|Reboot and enjoy]].<br />
<br />
=== Live CD === <!--T:9--> <br />
<br />
<!--T:10--><br />
In order to install Funtoo Linux, you will first need to boot your computer using a Linux-based Live CD or USB stick. We recommend the Gentoo-based [http://www.sysresccd.org/ System Rescue CD] as it contains lots of tools and utilities and supports both 32-bit and 64-bit systems. It can be burned to CD/DVD or installed on a USB stick. Download it here:<br />
<br />
<!--T:11--><br />
* Download from '''[http://ftp.osuosl.org/pub/funtoo/distfiles/sysresccd/sysresccd-20161103-4.9.0.iso osuosl.org]'''<br />
* Download from '''[http://build.funtoo.org/distfiles/sysresccd/sysresccd-20161103-4.9.0.iso funtoo.org]'''<br />
<br />
<!--T:12--><br />
{{Important|'''NO VIDEO''': We have patched our download of System Rescue CD so that it should initialize video properly when booting from UEFI (See {{bug|FL-2030}}.) If you are using the official, non-Funtoo System Rescue CD, at the GRUB menu, you may need to press {{c|e}} to edit the menu entry and add a GRUB boot line that reads {{c|insmod all_video}} and then boot. This bug has been reported upstream to System Rescue CD developers.}}<br />
<br />
<!--T:237--><br />
{{Note|If using an older version of System Rescue CD, '''be sure to select the <code>rescue64</code> kernel at the boot menu if you are installing a 64-bit system'''. By default, System Rescue CD used to boot in 32-bit mode though the latest version attempts to automatically detect 64-bit processors.}}<br />
<br />
==== Network Access ==== <!--T:13--> <br />
<br />
<!--T:14--><br />
Once you have booted System Rescue CD, see if you have Internet access. Internet access is required for installing Funtoo Linux:<br />
</translate><br />
<br />
<console><br />
# ##i##ping www.google.com<br />
PING www.google.com (216.58.217.36) 56(84) bytes of data.<br />
64 bytes from den03s10-in-f4.1e100.net (216.58.217.36): icmp_seq=1 ttl=57 time=30.1 ms<br />
</console><br />
<br />
<translate><br />
<!--T:15--><br />
If the ping is successful (you see <code>64 bytes</code> messages as above,) then your Network is set up. Hit Control-C to stop the ping. <br />
<br />
<!--T:16--><br />
If you need to set up a WiFi connection for Internet access, then this can be accomplished using the {{c|nmtui}} command-line tool:<br />
</translate><br />
{{console|body=<br />
# ##i##nmtui<br />
}}<br />
<br />
<translate><br />
==== Remote Install ==== <!--T:18--> <br />
<br />
<!--T:19--><br />
Alternatively, you can log into System Rescue CD over the network via SSH to perform the install from another computer, and this may be more convenient way to install Funtoo Linux.<br />
<br />
<!--T:20--><br />
If you'd like to complete the install remotely, here's how. First, you will need to ensure that System Rescue CD has a functioning network connection. Then, you will need to set a root password for System Rescue CD:<br />
</translate><br />
{{console|body=<br />
###i## passwd<br />
New password: ##i##********<br />
Retype new password: ##i##********<br />
passwd: password updated successfully<br />
}}<br />
<translate><br />
<!--T:21--><br />
Once you have typed in a password, you will now need to determine the IP address of System Rescue CD, and then you can use {{c|ssh}} to connect to it. To determine the IP address currently being used by System Rescue CD, type {{c|ifconfig}}:</translate><br />
<br />
{{console|body=<br />
###i## ifconfig<br />
}}<br />
<translate><!--T:238--><br />
Alternatively, determining of an IP address is possible with iproute2 {{c|ip}} tool:</translate><br />
<br />
{{console|body=<br />
###i## ip addr show<br />
}}<br />
<translate><!--T:22--><br />
One of the interfaces should have an IP address (listed as {{c|inet addr:}}) from your LAN. You can then connect remotely, from another system on your LAN, to System Rescue CD, and perform steps from the comfort of an existing OS. On your remote system, type the following, replacing {{c|1.2.3.4}} with the IP address of System Rescue CD. Connecting from an existing Linux or MacOS system would look something like this:</translate><br />
<br />
{{console|body=<br />
(remote system) $ ##i##ssh root@1.2.3.4<br />
Password: ##i##**********}}<br />
<translate><!--T:23--><br />
{{Note|If you'd like to connect remotely from an existing Microsoft Windows system, you'll need to download an SSH client for Windows, such as [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY].}}<br />
<br />
<!--T:24--><br />
After you've logged in via SSH, you're now connected remotely to System Rescue CD and can perform the installation steps.<br />
<br />
=== Prepare Hard Disk === <!--T:25--> <br />
<br />
<!--T:26--><br />
In this section, we'll learn about the different ways that Funtoo Linux can boot from a hard disk. By "boot", we mean the process by which Linux starts after you press the power button on your desktop, laptop or server. You can think of "booting" as a process that starts with your computer's firmware (built-in software) running, and then "finding" the Linux kernel and running it. The Linux kernel then takes over, identifies all your hardware, and starts.<br />
<br />
==== Background ==== <!--T:27--> <br />
<br />
<!--T:28--><br />
{{Note|If you are an absolute beginner to Linux, you may be less confused if you skip to the next section, [[#Which to Use?|Which to Use?]]}}<br />
<br />
<!--T:29--><br />
In earlier times, there was only one way to boot a PC-compatible computer. All of our desktops and servers had standard firmware called the "PC BIOS," all our hard drives used Master Boot Records at the beginning of the disk, where the PC BIOS would "look" to find boot loader code which would in turn load Linux, and our hard drives were partitioned into different regions using the standard MBR partition scheme. That was just how it was done. And we liked it that way!<br />
<br />
<!--T:30--><br />
Then, along came EFI and UEFI, which are new-style firmware designed to boot systems, along with GPT partition tables to define disk partitions on disks larger than 2.2TB. All of the sudden, we had a variety of options for installing and booting Linux systems, turning what once was a one-method-fits-all approach into something a lot more complex.<br />
<br />
<!--T:31--><br />
Let's take a moment to review the options available to you for configuring a hard drive to boot Funtoo Linux. This Install Guide uses, and recommends, the old-school method of BIOS booting and using an MBR. It works and (except for rare cases) is universally supported. There's nothing wrong with it. If your system disk is 2TB or smaller in size, it won't prevent you from using all of your disk's capacity, either.<br />
<br />
<!--T:32--><br />
But, there are some situations where the old-school method isn't optimal. If you have a system disk >2TB in size, then MBR partitions won't allow you to access all your storage. So that's one reason. Another reason is that there are some so-called "PC" systems out there that don't support BIOS booting anymore, and force you to use UEFI to boot. So, out of compassion for people who fall into this predicament, this Install Guide documents UEFI booting too.<br />
<br />
<!--T:33--><br />
Our recommendation is still to go old-school unless you have reason not to. The boot loader we will be using to load the Linux kernel in this guide is called GRUB, so we call this method the '''BIOS + GRUB (MBR)''' method. It's the traditional method of setting up a PC-compatible system to boot Linux.<br />
<br />
<!--T:34--><br />
If you need to use UEFI to boot, we recommend not using the MBR at all for booting, as some systems support this, but others don't. Instead, we recommend using UEFI to boot GRUB, which in turn will load Linux. We refer to this method as the '''UEFI + GRUB (GPT)''' method.<br />
<br />
<!--T:35--><br />
And yes, there are even more methods, some of which are documented on the [[Boot Methods]] page. We used to recommend a '''BIOS + GRUB (GPT)''' method but it is not consistently supported across a wide variety of hardware.<br />
<br />
==== Which to Use? ==== <!--T:36--><br />
<br />
<!--T:37--><br />
'''The big question is -- which boot method should you use?''' Here's how to tell.<br />
<br />
<!--T:38--><br />
;Principle 1 - Old School: If you can reliably boot System Rescue CD and it shows you an initial light blue menu, you are booting the CD using the BIOS, and it's likely that you can thus boot Funtoo Linux using the BIOS. So, go old-school and use BIOS booting, ''unless'' you have some reason to use UEFI, such as having a >2.2TB system disk. In that case, see Principle 2, as your system may also support UEFI booting.<br />
<br />
<!--T:39--><br />
;Principle 2 - New School: If you can reliably boot System Rescue CD and it shows you an initial black and white menu -- congratulations, your system is configured to support UEFI booting. This means that you are ready to install Funtoo Linux to boot via UEFI. Your system may still support BIOS booting, but just be trying UEFI first. You can poke around in your BIOS boot configuration and play with this.<br />
<br />
<!--T:40--><br />
{{Note|'''Advanced Users May Wonder:''' What's the Big Difference between Old School and New School?: Here's the deal. If you go with old-school MBR partitions, your {{f|/boot}} partition will be an ext2 filesystem, and you'll use {{c|fdisk}} to create your MBR partitions. If you go with new-school GPT partitions and UEFI booting, your {{f|/boot}} partition will be a vfat filesystem, because this is what UEFI is able to read, and you will use {{c|gdisk}} to create your GPT partitions. And you'll install GRUB a bit differently. That's about all it comes down to, in case you were curious.}}<br />
<br />
<!--T:41--><br />
To install Funtoo Linux to boot via the New School UEFI method, you must boot System Rescue CD using UEFI. If you successfully boot sysresccd with UEFI, you will see an initial black and white screen to select the mode in which you will boot system rescue cd. Otherwise, if you see a blue screen with black text, UEFI will not be active and you will not be able to set up UEFI booting later in the install process!<br />
<br />
<!--T:42--><br />
{{Note|'''Some motherboards may appear to support UEFI, but don't.''' Do your research. For example, the Award BIOS in my Gigabyte GA-990FXA-UD7 rev 1.1 has an option to enable UEFI boot for CD/DVD. '''This is not sufficient for enabling UEFI boot for hard drives and installing Funtoo Linux.''' UEFI must be supported for both removable media (so you can boot System Rescue CD using UEFI) as well as fixed media (so you can boot your new Funtoo Linux installation.) It turns out that later revisions of this board (rev 3.0) have a new BIOS that fully supports UEFI boot. This may point to a third principle -- know thy hardware.}}<br />
<br />
==== Old-School (BIOS/MBR) Method ==== <!--T:43--> <br />
<br />
<!--T:44--><br />
{{Note|Use this method if you are booting using your BIOS, and if your System Rescue CD initial boot menu was light blue. If you're going to use the new-school method, [[#New-School (UEFI/GPT) Method|click here to jump down to UEFI/GPT.]]}}<br />
<br />
<!--T:46--><br />
First, it's a good idea to make sure that you've found the correct hard disk to partition. Try this command and verify that {{f|/dev/sda}} is the disk that you want to partition:<br />
</translate><br />
{{console|body=<br />
###i## fdisk -l /dev/sda<br />
<br />
Disk /dev/sda: 640.1 GB, 640135028736 bytes, 1250263728 sectors<br />
Units = sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disk label type: gpt<br />
<br />
# Start End Size Type Name<br />
1 2048 1250263694 596.2G Linux filesyste Linux filesystem<br />
}}<br />
<translate><!--T:47--><br />
Now, it is recommended that you erase any existing MBR or GPT partition tables on the disk, which could confuse the system's BIOS at boot time. We accomplish this using {{c|sgdisk}}:<br />
{{Warning|This will make any existing partitions inaccessible! You are '''strongly''' cautioned and advised to backup any critical data before proceeding.}}</translate><br />
<br />
{{console|body=<br />
###i## sgdisk --zap-all /dev/sda<br />
<br />
Creating new GPT entries.<br />
GPT data structures destroyed! You may now partition the disk using fdisk or<br />
other utilities.<br />
}}<br />
<translate><!--T:48--><br />
This output is also nothing to worry about, as the command still succeded:</translate><br />
<br />
{{console|body=<br />
***************************************************************<br />
Found invalid GPT and valid MBR; converting MBR to GPT format<br />
in memory. <br />
***************************************************************<br />
}}<translate><br />
<!--T:50--><br />
Now we will use {{c|fdisk}} to create the MBR partition table and partitions:<br />
</translate><br />
{{console|body=<br />
###i## fdisk /dev/sda<br />
}}<br />
<translate><br />
<!--T:51--><br />
Within {{c|fdisk}}, follow these steps:<br />
<br />
<!--T:52--><br />
'''Empty the partition table''':<br />
</translate><br />
{{console|body=<br />
Command (m for help): ##i##o ↵<br />
}}<br />
<translate><!--T:53--><br />
'''Create Partition 1''' (boot):</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (1-4, default 1): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+128M ↵<br />
}}<br />
<translate><!--T:54--><br />
'''Create Partition 2''' (swap):</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (2-4, default 2): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+2G ↵<br />
Command (m for help): ##i##t ↵ <br />
Partition number (1,2, default 2): ##i## ↵<br />
Hex code (type L to list all codes): ##i##82 ↵<br />
}}<br />
<translate><!--T:55--><br />
'''Create the root partition:'''</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##n ↵<br />
Partition type (default p): ##i##↵<br />
Partition number (3,4, default 3): ##i##↵<br />
First sector: ##i##↵<br />
Last sector: ##i##↵<br />
}}<br />
<translate><!--T:56--><br />
'''Verify the partition table:'''</translate><br />
<br />
{{console|body=<br />
Command (m for help): ##i##p<br />
<br />
Disk /dev/sda: 298.1 GiB, 320072933376 bytes, 625142448 sectors<br />
Units: sectors of 1 * 512 = 512 bytes<br />
Sector size (logical/physical): 512 bytes / 512 bytes<br />
I/O size (minimum/optimal): 512 bytes / 512 bytes<br />
Disklabel type: dos<br />
Disk identifier: 0x82abc9a6<br />
<br />
Device Boot Start End Blocks Id System<br />
/dev/sda1 2048 264191 131072 83 Linux<br />
/dev/sda2 264192 4458495 2097152 82 Linux swap / Solaris<br />
/dev/sda3 4458496 625142447 310341976 83 Linux<br />
}}<br />
<translate><!--T:57--><br />
'''Write the partition table to disk:'''</translate><br />
<br />
{{console|body=Command (m for help): ##i##w}}<br />
<translate><!--T:58--><br />
Your new MBR partition table will now be written to your system disk.<br />
<br />
<!--T:59--><br />
{{Note|You're done with partitioning! Now, jump over to [[#Creating filesystems|Creating filesystems]].}}<br />
<br />
==== New-School (UEFI/GPT) Method ==== <!--T:60--> <br />
<br />
<!--T:61--><br />
{{Note|Use this method if you are interested in booting using UEFI, and if your System Rescue CD initial boot menu was black and white. If it was light blue, this method will not work.}}<br />
<br />
<!--T:62--><br />
The {{c|gdisk}} commands to create a GPT partition table are as follows. Adapt sizes as necessary, although these defaults will work for most users. Start {{c|gdisk}}:<br />
</translate><br />
{{console|body=###i## gdisk /dev/sda}}<br />
<translate><!--T:63--><br />
Within {{c|gdisk}}, follow these steps:<br />
<br />
<!--T:64--><br />
'''Create a new empty partition table''' (This ''will'' erase all data on the disk when saved):<br />
</translate><br />
{{console|body=<br />
Command: ##i##o ↵<br />
This option deletes all partitions and creates a new protective MBR.<br />
Proceed? (Y/N): ##i##y ↵<br />
}}<br />
<translate><!--T:65--><br />
'''Create Partition 1''' (boot):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##1 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+500M ↵<br />
Hex Code: ##i##EF00 ↵<br />
}}<br />
<translate><!--T:66--><br />
'''Create Partition 2''' (swap):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##2 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##+4G ↵<br />
Hex Code: ##i##8200 ↵<br />
}}<br />
<translate><!--T:67--><br />
'''Create Partition 3''' (root):</translate><br />
<br />
{{console|body=<br />
Command: ##i##n ↵<br />
Partition Number: ##i##3 ↵<br />
First sector: ##i##↵<br />
Last sector: ##i##↵##!i## (for rest of disk)<br />
Hex Code: ##i##↵<br />
}}<br />
<translate><!--T:68--><br />
Along the way, you can type "{{c|p}}" and hit Enter to view your current partition table. If you make a mistake, you can type "{{c|d}}" to delete an existing partition that you created. When you are satisfied with your partition setup, type "{{c|w}}" to write your configuration to disk:<br />
<br />
<!--T:69--><br />
'''Write Partition Table To Disk''':<br />
</translate><br />
{{console|body=<br />
Command: ##i##w ↵<br />
Do you want to proceed? (Y/N): ##i##Y ↵<br />
}}<translate><br />
<!--T:70--><br />
The partition table will now be written to the disk and {{c|gdisk}} will close.<br />
<br />
<!--T:71--><br />
Now, your GPT/GUID partitions have been created, and will show up as the following ''block devices'' under Linux:<br />
<br />
<!--T:72--><br />
* {{c|/dev/sda1}}, which will be used to hold the {{c|/boot}} filesystem, <br />
<br />
<!--T:73--><br />
* {{c|/dev/sda2}}, which will be used for swap space, and <br />
<br />
<!--T:74--><br />
* {{c|/dev/sda3}}, which will hold your root filesystem.<br />
<br />
{{Tip|You can verify that the block devices above were correctly created by running the command {{c|lsblk}}.}}<br />
==== Creating filesystems ==== <!--T:75--> <br />
<br />
<!--T:76--><br />
{{Note|This section covers both BIOS ''and'' UEFI installs. Don't skip it!}}<br />
<br />
<!--T:77--><br />
Before your newly-created partitions can be used, the block devices that were created in the previous step need to be initialized with filesystem ''metadata''. This process is known as ''creating a filesystem'' on the block devices. After filesystems are created on the block devices, they can be mounted and used to store files.<br />
<br />
<!--T:78--><br />
Let's keep this simple. Are you using old-school MBR partitions? If so, let's create an ext2 filesystem on {{f|/dev/sda1}}:<br />
</translate><br />
{{console|body=###i## mkfs.ext2 /dev/sda1}}<br />
<translate><!--T:79--><br />
If you're using new-school GPT partitions for UEFI, you'll want to create a vfat filesystem on {{c|/dev/sda1}}, because this is what UEFI is able to read:<br />
</translate><br />
{{console|body=###i## mkfs.vfat -F 32 /dev/sda1}}<br />
<translate><!--T:80--><br />
Now, let's create a swap partition. This partition will be used as disk-based virtual memory for your Funtoo Linux system.<br />
<br />
<!--T:81--><br />
You will not create a filesystem on your swap partition, since it is not used to store files. But it is necessary to initialize it using the {{c|mkswap}} command. Then we'll run the {{c|swapon}} command to make your newly-initialized swap space immediately active within the live CD environment, in case it is needed during the rest of the install process:<br />
</translate><br />
{{console|body=<br />
# ##i##mkswap /dev/sda2<br />
# ##i##swapon /dev/sda2<br />
}}<translate><br />
<!--T:82--><br />
Now, we need to create a root filesystem. This is where Funtoo Linux will live. We generally recommend ext4 or XFS root filesystems. If you're not sure, choose ext4. Here's how to create a root ext4 filesystem:</translate><br />
<br />
{{console|body=###i## mkfs.ext4 /dev/sda3}}<br />
<translate><!--T:83--><br />
...and here's how to create an XFS root filesystem, if you prefer to use XFS instead of ext4:</translate><br />
<br />
{{console|body=###i## mkfs.xfs /dev/sda3}}<br />
<translate><!--T:84--><br />
Your filesystems (and swap) have all now been initialized, so that that can be mounted (attached to your existing directory heirarchy) and used to store files. We are ready to begin installing Funtoo Linux on these brand-new filesystems.<br />
<br />
<!--T:85--><br />
{{Warning|When deploying an OpenVZ host, please use ext4 exclusively. The Parallels development team tests extensively with ext4, and modern versions of {{c|openvz-rhel6-stable}} are '''not''' compatible with XFS, and you may experience kernel bugs.}}<br />
<br />
==== Mounting filesystems ==== <!--T:86--> <br />
<br />
<!--T:87--><br />
Mount the newly-created filesystems as follows, creating {{c|/mnt/funtoo}} as the installation mount point:<br />
</translate><br />
{{console|body=<br />
###i## mkdir /mnt/funtoo<br />
###i## mount /dev/sda3 /mnt/funtoo<br />
###i## mkdir /mnt/funtoo/boot<br />
###i## mount /dev/sda1 /mnt/funtoo/boot<br />
}}<br />
<translate><!--T:88--><br />
Optionally, if you have a separate filesystem for {{f|/home}} or anything else:</translate><br />
<br />
{{console|body=<br />
###i## mkdir /mnt/funtoo/home<br />
###i## mount /dev/sda4 /mnt/funtoo/home<br />
}}<br />
<translate><!--T:89--><br />
If you have {{f|/tmp}} or {{f|/var/tmp}} on a separate filesystem, be sure to change the permissions of the mount point to be globally-writeable after mounting, as follows:</translate><br />
{{console|body=###i## chmod 1777 /mnt/funtoo/tmp}}<translate><br />
<br />
==== Setting the Date ==== <!--T:90--> <br />
<br />
<!--T:91--><br />
{{Important|If your system's date and time are too far off (typically by months or years,) then it may prevent Portage from properly downloading source tarballs. This is because some of our sources are downloaded via HTTPS, which use SSL certificates and are marked with an activation and expiration date. However, if your system time is relatively close to correct, you can probably skip this step for now.}}<br />
<br />
<!--T:92--><br />
Now is a good time to verify the date and time are correctly set to UTC. Use the {{c|date}} command to verify the date and time:<br />
</translate><br />
{{console|body=<br />
###i## date<br />
Fri Jul 15 19:47:18 UTC 2011<br />
}}<br />
<translate><!--T:93--><br />
If the date and/or time need to be corrected, do so using {{c|date MMDDhhmmYYYY}}, keeping in mind {{c|hhmm}} are in 24-hour format. The example below changes the date and time to "July 16th, 2011 @ 8:00PM" UTC:</translate><br />
<br />
{{console|body=<br />
###i## date 071620002011<br />
Fri Jul 16 20:00:00 UTC 2011<br />
}}<br />
<translate><!--T:94--><br />
Once you have set the system clock, it's a very good idea to copy the time to the hardware clock, so it persists across reboots:</translate><br />
<br />
{{console|body=###i## hwclock --systohc}}<br />
<translate><br />
=== Installing the Stage 3 tarball === <!--T:95--> <br />
<br />
<!--T:96--><br />
Now that filesystems are created and your hardware and system clock are set, the next step is downloading the initial Stage 3 tarball. The Stage 3 is a pre-compiled system used as a starting point to install Funtoo Linux. <br />
<br />
<!--T:97--><br />
To download the correct build of Funtoo Linux for your system, head over to the [[Subarches]] page. Subarches are builds of Funtoo Linux that are designed to run on a particular type of CPU, to offer the best possible performance. They also take advantage of the instruction sets available for each CPU.<br />
<br />
If you don't know which subarch to choose, issue this command:<br />
<console><br />
###i## gcc -march=native -Q --help=target | grep march<br />
</console><br />
<br />
<!--T:98--><br />
The [[Subarches]] page lists all CPU-optimized versions of Funtoo Linux. Find the one that is appropriate for the type of CPU that your system has, and then click on its name in the first column (such as {{c|corei7}}, for example.) You will then go to a page dedicated to that subarch, and the stage3s available for download will be listed. If you are using a virtualization technology to run Funtoo Linux, and your VM may migrate to different types of hardware, then it's recommended that you use a stage3 that is optimized for the oldest CPU instruction set that your VM will run on, or a generic image if it may run on both AMD and Intel processors.<br />
<br />
<!--T:99--><br />
For most subarches, you will have several stage3s available to choose from. This next section will help you understand which one to pick.<br />
<br />
==== Which Build? ==== <!--T:100--> <br />
<br />
<!--T:101--><br />
''Pick {{c|funtoo-current}}.'''<br />
<br />
==== Which Variant? ==== <!--T:104--> <br />
<br />
<!--T:105--><br />
If you're not sure, pick {{c|standard}}.<br />
<br />
<!--T:106--><br />
Our "regular" stage3's are listed with a variant of {{c|standard}}. The following variant builds are available:<br />
<br />
<!--T:107--><br />
{{TableStart}}<br />
{{2ColHead|Variant|Description}}<br />
<tr><td>{{c|standard}}</td><td>The "standard" version of Funtoo Linux</td></tr><br />
<tr><td>{{c|pure64}}</td><td>A 64-bit build that drops multilib (32-bit compatibility) support. Can be ideal for server systems.</td></tr><br />
<tr><td>{{c|hardened}}</td><td>Includes PIE/SSP toolchain for enhanced security. PIE does require the use of PaX in the kernel, while SSP works with any kernel, and provides enhanced security in user-space to avoid stack-based exploits. For expert users.</td></tr><br />
{{TableEnd}}<br />
<br />
==== Download the Stage3 ==== <!--T:108--> <br />
<br />
<!--T:109--><br />
Once you have found the stage3 that you would like to download, use {{c|wget}} to download the Stage 3 tarball you have chosen to use as the basis for your new Funtoo Linux system. It should be saved to the {{f|/mnt/funtoo}} directory as follows:<br />
</translate><br />
{{console|body=<br />
###i## cd /mnt/funtoo<br />
###i## wget http://build.funtoo.org/funtoo-current/x86-64bit/generic_64/stage3-latest.tar.xz<br />
}}<br />
<translate><!--T:110--><br />
Note that 64-bit systems can run 32-bit or 64-bit stages, but 32-bit systems can only run 32-bit stages. Make sure that you select a Stage 3 build that is appropriate for your CPU. If you are not certain, it is a safe bet to choose the {{c|generic_64}} or {{c|generic_32}} stage. Consult the [[Subarches]] page for more information.<br />
<br />
<!--T:111--><br />
Once the stage is downloaded, extract the contents with the following command, substituting in the actual name of your Stage 3 tarball:</translate><br />
{{console|body=<br />
###i## tar xpf stage3-latest.tar.xz<br />
}}<translate><br />
<!--T:112--><br />
{{Important|It is very important to use {{c|tar's}} "{{c|'''p'''}}" option when extracting the Stage 3 tarball - it tells {{c|tar}} to ''preserve'' any permissions and ownership that exists within the archive. Without this option, your Funtoo Linux filesystem permissions will be incorrect.}}<br />
<br />
=== Chroot into Funtoo === <!--T:113--><br />
To install Funtoo Linux, the {{c|chroot}} command is first used. The chroot command will "switch into" the new Funtoo Linux system, so the commands you execute after running "chroot" will run within your newly-extracted Funtoo Linux system.<br />
<br />
<!--T:114--><br />
Before chrooting, there are a few things that need to be done to set up the chroot environment. You will need to mount {{f|/proc}}, {{f|/sys}} and {{f|/dev}} inside your new system. Use the following commands to do so:</translate><br />
{{console|body=<br />
# ##i##cd /mnt/funtoo<br />
# ##i##mount -t proc none proc<br />
# ##i##mount --rbind /sys sys<br />
# ##i##mount --rbind /dev dev<br />
}}<translate><br />
<!--T:115--><br />
You'll also want to copy over {{f|resolv.conf}} in order to have proper resolution of Internet hostnames from inside the chroot:</translate><br />
{{console|body=<br />
# ##i##cp /etc/resolv.conf /mnt/funtoo/etc/<br />
}}<translate><br />
<!--T:116--><br />
Now you can chroot into your new system. Use <code>env</code> before <code>chroot</code> to ensure that no environment settings from the installation media are pulled in to your new system:</translate><br />
<br />
{{console|body=###i## env -i HOME=/root TERM=$TERM /bin/chroot . bash -l}}<br />
<translate><!--T:117--><br />
{{Note|For users of live CDs with 64-bit kernels installing 32-bit systems: Some software may use {{c|uname -r}} to check whether the system is 32 or 64-bit. You may want append linux32 to the chroot command as a workaround, but it's generally not needed.}}<br />
{{Important|If you receive the error "{{c|chroot: failed to run command `/bin/bash': Exec format error}}", it is most likely because you are running a 32-bit kernel and trying to execute 64-bit code. Make sure that you have selected the proper type of kernel when booting SystemRescueCD.}}<br />
<br />
<!--T:118--><br />
It's also a good idea to change the default command prompt while inside the chroot. This will avoid confusion if you have to change terminals. Use this command:<br />
{{console|body=# ##i##export PS1="(chroot) $PS1"}}<br />
Test internet name resolution from within the chroot:<br />
{{console|body=###i## ping -c 5 google.com}}<br />
If you can't ping, make sure {{f|/etc/resolv.conf}} doesn't contain things like {{c|127.0.x.x}} addresses, if it does, change the {{c|127.0.x.x}} entry to {{c|8.8.8.8}} -- Google's public dns address. Make sure to replace this with your dns of choice once the system is installed.<br />
<br />
<br />
Congratulations! You are now chrooted inside a Funtoo Linux system. Now it's time to get Funtoo Linux properly configured so that Funtoo Linux will start successfully, without any manual assistance, when your system is restarted.<br />
<br />
=== Downloading the Portage tree === <!--T:120--> <br />
<br />
Now it's time to install a copy of the Portage repository, which contains package scripts (ebuilds) that tell portage how to build and install thousands of different software packages. To create the Portage repository, simply run {{c|ego sync}} from within the chroot. This will automatically clone the portage tree from [https://github.com/funtoo/meta-repo GitHub] and all kit submodules:<br />
<br />
{{console|body=<br />
(chroot) ###i## cd /var/tmp<br />
(chroot) ###i## ego sync<br />
}}<br />
<br />
{{Note|The {{c|cd /var/tmp}} command works around a bug that is fixed in ego-2.3.0.}}<br />
<br />
=== Configuring your system === <!--T:123--><br />
As is expected from a Linux distribution, Funtoo Linux has its share of configuration files. The one file you are absolutely required to edit in order to ensure that Funtoo Linux boots successfully is {{f|/etc/fstab}}. The others are optional. <br />
<br />
==== Using Nano ==== <!--T:124--> <br />
<br />
<!--T:125--><br />
The default editor included in the chroot environment is called {{c|nano}}. To edit one of the files below, run nano as follows:<br />
<br />
<!--T:126--><br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/fstab<br />
}}<br />
When in the editor, you can use arrow keys to move the cursor, and common keys like backspace and delete will work as expected. To save the file, press Control-X, and answer {{c|y}} when prompted to save the modified buffer if you would like to save your changes.<br />
<br />
==== Configuration Files ==== <!--T:127--> <br />
<br />
<!--T:128--><br />
Here are a full list of files that you may want to edit, depending on your needs:<br />
{{TableStart}}<br />
{{3ColHead|File|Do I need to change it?|Description}}<br />
<tr class="danger"><br />
<td>{{c|/etc/fstab}}</td><br />
<td>'''YES - required'''</td><br />
<td>Mount points for all filesystems to be used at boot time. This file must reflect your disk partition setup. We'll guide you through modifying this file below.</td><br />
</tr><tr><br />
<td>{{c|/etc/localtime}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Your timezone, which will default to UTC if not set. This should be a symbolic link to something located under /usr/share/zoneinfo (e.g. /usr/share/zoneinfo/America/Montreal) </td><br />
</tr><tr><br />
<td>{{c|/etc/portage/make.conf}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Parameters used by gcc (compiler), portage, and make. ''Note that it is normal for this file to be empty in Funtoo Linux, as many settings have been migrated to our enhanced profile system.''</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/hostname}}</td><br />
<td>''Maybe - recommended''</td><br />
<td>Used to set system hostname. Set the {{c|hostname}} variable to the fully-qualified (with dots, ie. {{c|foo.funtoo.org}}) name if you have one. Otherwise, set to the local system hostname (without dots, ie. {{c|foo}}). Defaults to {{c|localhost}} if not set.</td><br />
</tr><tr><br />
<td>{{c|/etc/hosts}}</td><br />
<td>''No''</td><br />
<td> You no longer need to manually set the hostname in this file. This file is automatically generated by {{c|/etc/init.d/hostname}}.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/keymaps}}</td><br />
<td>Optional</td><br />
<td>Keyboard mapping configuration file (for console pseudo-terminals). Set if you have a non-US keyboard. See [[Funtoo Linux Localization]].</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/hwclock}}</td><br />
<td>Optional</td><br />
<td>How the time of the battery-backed hardware clock of the system is interpreted (UTC or local time). Linux uses the battery-backed hardware clock to initialize the system clock when the system is booted.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/modules}}</td><br />
<td>Optional</td><br />
<td>Kernel modules to load automatically at system startup. Typically not required. See [[Additional Kernel Resources]] for more info.</td><br />
</tr><tr><br />
<td>{{c|/etc/conf.d/consolefont}}</td><br />
<td>Optional</td><br />
<td>Allows you to specify the default console font. To apply this font, enable the consolefont service by running rc-update add consolefont.</td><br />
</tr><tr><br />
<td>{{c|profiles}}</td><br />
<td>Optional</td><br />
<td>Some useful portage settings that may help speed up intial configuration.</td><br />
</tr><br />
{{TableEnd}}<br />
<br />
<!--T:129--><br />
If you're installing an English version of Funtoo Linux, you're in luck, as most of the configuration files can be used as-is. If you're installing for another locale, don't worry. We will walk you through the necessary configuration steps on the [[Funtoo Linux Localization]] page, and if needed, there's always plenty of friendly, helpful support available. (See [[Getting Help]])<br />
<br />
<!--T:130--><br />
Let's go ahead and see what we have to do. Use {{c|nano -w <name_of_file>}} to edit files -- the "{{c|-w}}" argument disables word-wrapping, which is handy when editing configuration files. You can copy and paste from the examples.<br />
<br />
<!--T:131--><br />
{{Warning|It's important to edit your {{c|/etc/fstab}} file before you reboot! You will need to modify both the "fs" and "type" columns to match the settings for your partitions and filesystems that you created with {{c|gdisk}} or {{c|fdisk}}. Skipping this step may prevent Funtoo Linux from booting successfully.}}<br />
<br />
==== /etc/fstab ==== <!--T:132--><br />
<br />
<!--T:133--><br />
{{f|/etc/fstab}} is used by the {{c|mount}} command which is run when your system boots. Lines in this file inform {{c|mount}} about filesystems to be mounted and how they should be mounted. In order for the system to boot properly, you must edit {{f|/etc/fstab}} and ensure that it reflects the partition configuration you used earlier in the install process. If you can't remember the partition configuration that you used earlier, the {{c|lsblk}} command may be of help to you:<br />
</translate><br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/fstab<br />
}}<br />
{{file|name=/etc/fstab|desc=An example fstab file|body=<br />
# The root filesystem should have a pass number of either 0 or 1.<br />
# All other filesystems should have a pass number of 0 or greater than 1.<br />
#<br />
# NOTE: If your BOOT partition is ReiserFS, add the notail option to opts.<br />
#<br />
# See the manpage fstab(5) for more information.<br />
#<br />
# <fs> <mountpoint> <type> <opts> <dump/pass><br />
<br />
/dev/sda1 /boot ext2 noauto,noatime 1 2<br />
/dev/sda2 none swap sw 0 0<br />
/dev/sda3 / ext4 noatime 0 1<br />
#/dev/cdrom /mnt/cdrom auto noauto,ro 0 0<br />
}}<br />
<translate><br />
<!--T:135--><br />
{{Note|If you're using UEFI to boot, change the {{f|/dev/sda1}} line so that it says {{c|vfat}} instead of {{c|ext2}}. Similarly, make sure that the {{f|/dev/sda3}} line specifies either {{c|xfs}} or {{c|ext4}}, depending on which filesystem you chose earlier on in the installation process when you created filesystems.}}<br />
<br />
==== /etc/localtime ==== <!--T:136--> <br />
<br />
<!--T:137--><br />
{{f|/etc/localtime}} is used to specify the timezone that your machine is in, and defaults to UTC. If you would like your Funtoo Linux system to use local time, you should replace {{f|/etc/localtime}} with a symbolic link to the timezone that you wish to use. <br />
<br />
<!--T:138--><br />
{{console|body=<br />
(chroot) ###i## ln -sf /usr/share/zoneinfo/MST7MDT /etc/localtime<br />
}}<br />
The above sets the timezone to Mountain Standard Time (with daylight savings). Type {{c|ls /usr/share/zoneinfo}} to list available timezones. There are also sub-directories containing timezones described by location.<br />
<br />
==== /etc/portage/make.conf ==== <!--T:139--> <br />
<br />
<!--T:140--><br />
{{c|USE}} flags define what functionality is enabled when packages are built. It is not recommended to add a lot of USE flags during installation; you should wait until you have a working, bootable system before changing your USE flags. A USE flag prefixed with a minus ("{{c|-}}") sign tells Portage not to use the flag when compiling. A Funtoo guide to USE flags will be available in the future. For now, you can find out more information about USE flags in the [https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/USE Gentoo Handbook].<br />
<br />
==== /etc/conf.d/hwclock ==== <!--T:147--><br />
If you dual-boot with Windows, you'll need to edit this file and change the value of '''clock''' from '''UTC''' to '''local''', because Windows will set your hardware clock to local time every time you boot Windows. Otherwise you normally wouldn't need to edit this file.<br />
{{console|body=<br />
(chroot) ###i## nano -w /etc/conf.d/hwclock<br />
}}<br />
==== Localization ====<br />
<br />
<!--T:148--><br />
By default, Funtoo Linux is configured with Unicode (UTF-8) enabled, and for the US English locale and keyboard. If you would like to configure your system to use a non-English locale or keyboard, see [[Funtoo Linux Localization]].<br />
<br />
=== Introducing Portage === <!--T:149--> <br />
<br />
<!--T:150--><br />
Portage, the Funtoo Linux package manager has a command called <code>emerge</code> which is used to build and install packages from source. It also takes care of installing all of the package's dependencies. You call emerge like this:<br />
<br />
<!--T:151--><br />
<console><br />
(chroot) # ##i##emerge packagename<br />
</console><br />
<br />
<!--T:152--><br />
When you install a package by specifying its name in the command-line, Portage records its name in the <code>/var/lib/portage/world</code> file. It does so because it assumes that, since you have installed it by name, you want to consider it part of your system and want to keep the package updated in the future. This is a handy feature, since when packages are being added to the <code>world</code> set, we can update our entire system by typing:<br />
<br />
<!--T:153--><br />
<console><br />
(chroot) # ##i##ego sync<br />
(chroot) # ##i##emerge -auDN @world<br />
</console><br />
<br />
<!--T:154--><br />
This is the "official" way to update your Funtoo Linux system. Above, we first update our Portage tree using git to grab the latest ebuilds (scripts), and then run an emerge command to update the <code>world</code> set of packages. The options specified tell <code>emerge</code> to:<br />
<br />
<!--T:155--><br />
* '''<code>a</code>''' - show us what will be emerged, and '''ask''' us if we want to proceed<br />
* '''<code>u</code>''' - '''update''' the packages we specify -- don't emerge them again if they are already emerged.<br />
* '''<code>D</code>''' - Consider the entire dependency tree of packages when looking for updates. In other words, do a '''deep''' update.<br />
* '''<code>N</code>''' - Update any packages that have changed ('''new''') USE settings.<br />
<br />
<!--T:156--><br />
You should also consider passing <code>--with-bdeps=y</code> when emerging @world, at least once in a while. This will update build dependencies as well.<br />
<br />
<!--T:157--><br />
Of course, sometimes we want to install a package but not add it to the <code>world</code> file. This is often done because you only want the package installed temporarily or because you know the package in question is a dependency of another package. If this behavior is desired, you call emerge like this:<br />
<br />
<!--T:158--><br />
<console><br />
(chroot) # ##i##emerge -1 packagename<br />
</console><br />
<br />
<!--T:159--><br />
Advanced users may be interested in the [[Emerge]] wiki page.<br />
<br />
==== Updating World ==== <!--T:160--> <br />
<br />
<!--T:161--><br />
Certain packages in the Funtoo tarball have to be compiled with the bindist USE flag set; as a result of this, it can cause problems with updating other packages later. So now you must update the entire system before first boot in order to rebuild all packages that have the bindist USE flag set:<br />
<br />
<!--T:162--><br />
<console><br />
(chroot) # ##i##ego sync<br />
(chroot) # ##i##emerge -auDN @world<br />
</console><br />
<br />
<!--T:163--><br />
{{fancyimportant|1=<br />
Make sure you read any post emerge messages and follow their instructions. This is especially true if you have upgraded perl or python.}}<br />
<br />
=== Kernel === <!--T:164--> <br />
<br />
<!--T:165--><br />
Starting mid-May 2015, Funtoo Linux stage3's include a pre-built {{c|debian-sources}} kernel to make installation faster and easier. To see if debian-sources is installed, type:<br />
</translate><br />
{{console|body=<br />
(chroot) # ##i##emerge -s debian-sources<br />
Searching... <br />
[ Results for search key : ##b##debian-sources##!b## ]<br />
[ Applications found : ##b##1##!b## ]<br />
<br />
* ##b##sys-kernel/debian-sources##!b##<br />
##g##Latest version available:##!g## 3.19.3<br />
##g##Latest version installed:##!g## 3.19.3<br />
##g##Size of files:##!g## 81,292 kB<br />
##g##Homepage:##!g## http://www.debian.org<br />
##g##Description:##!g## Debian Sources (and optional binary kernel)<br />
##g##License:##!g## GPL-2<br />
}}<br />
<translate><br />
<!--T:166--><br />
If a version is listed under {{c|Latest version installed}}, then debian-sources is already pre-built for you and you can skip the rest of the Kernel section, and proceed to the [[#Installing a Bootloader|Installing a Bootloader section]].<br />
<br />
==== Building the Kernel ==== <!--T:167--> <br />
<br />
<!--T:168--><br />
If you need to build a kernel for Funtoo Linux, please follow these steps:<br />
<br />
<!--T:169--><br />
{{Fancynote|1=<br />
See [[Funtoo Linux Kernels]] for a full list of kernels supported in Funtoo Linux. We recommend <code>debian-sources</code> for new users.}}<br />
<br />
<!--T:170--><br />
{{fancyimportant|1=<br />
<code>debian-sources</code> with <code>binary</code> USE flag requires at least 20GB free in <code>/var/tmp</code> and takes around 1 hour to build on a Intel Core i7 Processor.}}<br />
<br />
<!--T:171--><br />
Let's emerge our kernel:<br />
<br />
<!--T:172--><br />
<console><br />
(chroot) # ##i##emerge debian-sources<br />
</console><br />
<br />
<!--T:173--><br />
Once <code>emerge</code> completes, you'll have a brand new kernel and initramfs installed to <code>/boot</code>, plus kernel headers installed in <code>/usr/src/linux</code>, and you'll be ready to configure the boot loader to load these to boot your Funtoo Linux system.<br />
<br />
<!--T:174--><br />
{{warning|If you have a RAID in your machine, the kernel installation will pull in the <code>mdadm</code> tool as a dependency. It is important to edit the <code>/etc/mdadm.conf</code> file prior to rebooting the machine so the RAID is properly recognised and set up before the kernel attempts to mount it in the tree. Failing to do so can result in an unusable or even unbootable system! For specific details, consult the mdadm man page <code>man mdadm</code> or the [[Package:Mdadm|mdadm]] ebuild page.}}<br />
<br />
<!--T:175--><br />
{{fancynote|NVIDIA card users: the <code>binary</code> USE flag installs the Nouveau drivers which cannot be loaded at the same time as the proprietary drivers, and cannot be unloaded at runtime because of KMS. You need to blacklist it under <code>/etc/modprobe.d/</code>.}}<br />
<br />
<!--T:176--><br />
{{fancynote|For an overview of other kernel options for Funtoo Linux, see [[Funtoo Linux Kernels]]. There may be modules that the Debian kernel doesn't include, a situation where [http://www.funtoo.org/wiki/Funtoo_Linux_Kernels#Using_Debian-Sources_with_Genkernel genkernel] would be useful. Also be sure to see [[:Category:Hardware Compatibility|hardware compatibility]] information.}}<br />
<br />
=== Installing a Bootloader === <!--T:177--><br />
<br />
<!--T:178--><br />
These install instructions show you how to use GRUB to boot using BIOS (old-school) or UEFI (new-school). As of boot-update-1.7.2, now in Portage, the steps are very similar.<br />
<br />
<!--T:179--><br />
First, emerge <code>boot-update</code>. This will also cause <code>grub-2</code> and {{c|efibootmgr}} to be merged, since they are dependencies:<br />
<br />
<!--T:180--><br />
<console><br />
(chroot) # ##i##emerge boot-update<br />
</console><br />
<br />
<!--T:181--><br />
Then, edit <code>/etc/boot.conf</code> using {{c|nano}} and specify "<code>Funtoo Linux genkernel</code>" as the <code>default</code> setting at the top of the file, replacing <code>"Funtoo Linux"</code>. Also, if you're not using memtest86+ remove the entry in boot.conf to avoid errors.<br />
<br />
<!--T:182--><br />
<code>/etc/boot.conf</code> should now look like this:<br />
</translate><br />
{{file|name=/etc/boot.conf|body=<br />
boot {<br />
generate grub<br />
default "Funtoo Linux genkernel" <br />
timeout 3 <br />
}<br />
<br />
"Funtoo Linux" {<br />
kernel bzImage[-v]<br />
}<br />
<br />
"Funtoo Linux genkernel" {<br />
kernel kernel[-v]<br />
initrd initramfs[-v]<br />
params += real_root=auto <br />
} <br />
<br />
"Funtoo Linux better-initramfs" {<br />
kernel vmlinuz[-v]<br />
initrd /initramfs.cpio.gz<br />
}<br />
}}<br />
<translate><br />
<!--T:183--><br />
If you are booting a custom or non-default kernel, please read <code>man boot.conf</code> for information on the various options available to you.<br />
<br />
==== Old School (BIOS) MBR ==== <!--T:184--> <br />
<br />
<!--T:185--><br />
When using "old school" BIOS booting, run the following command to install GRUB to your MBR, and generate the {{c|/boot/grub/grub.cfg}} configuration file that GRUB will use for booting:<br />
<br />
<!--T:186--><br />
<console><br />
(chroot) # ##i##grub-install --target=i386-pc --no-floppy /dev/sda<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
==== New School (UEFI) Boot Entry ==== <!--T:187--><br />
<br />
<!--T:188--><br />
If you're using "new school" UEFI booting, run of the following sets of commands, depending on whether you are installing a 64-bit or 32-bit system. This will add GRUB as a UEFI boot entry.<br />
<br />
<!--T:189--><br />
For x86-64bit systems:<br />
<br />
<!--T:190--><br />
<console><br />
(chroot) # ##i##grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
<!--T:191--><br />
For x86-32bit systems:<br />
<br />
<!--T:192--><br />
<console><br />
(chroot) # ##i##grub-install --target=i386-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda<br />
(chroot) # ##i##boot-update<br />
</console><br />
<br />
==== First Boot, and in the future... ==== <!--T:193--> <br />
<br />
<!--T:194--><br />
OK -- you are almost ready to boot! <br />
<br />
<!--T:195--><br />
You only need to run <code>grub-install</code> when you first install Funtoo Linux, but you need to re-run <code>boot-update</code> every time you modify your <code>/etc/boot.conf</code> file or add new kernels to your system. This will regenerate {{c|/boot/grub/grub.cfg}} so that you will have new kernels available in your GRUB boot menu, the next time you reboot.<br />
<br />
=== Configuring your network === <!--T:196--> <br />
<br />
<!--T:197--><br />
It's important to ensure that you will be able to connect to your local-area network after you reboot into Funtoo Linux. There are three approaches you can use for configuring your network: NetworkManager, dhcpcd, and the [[Funtoo Linux Networking]] scripts. Here's how to choose which one to use based on the type of network you want to set up.<br />
<br />
==== Wi-Fi ==== <!--T:198--><br />
<br />
<!--T:232--><br />
For laptop/mobile systems where you will be using Wi-Fi, roaming, and connecting to various networks NetworkManager is strongly recommended. <br />
Since Wi-Fi cards require firmware to operate, it is also recommended that you emerge the linux-firmware ebuild:<br />
<br />
<!--T:233--><br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager<br />
}}<br />
<br />
Depending on your architecture, you might now see a message similar to the following:<br />
<br />
{{console|body=<br />
The following USE changes are necessary to proceed<br />
...<br />
}}<br />
This means that your USE flags need to be updated to allow this installation. For now, you can let portage handle this for you by adding the flag <code>--autounmask-write</code>:<br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager --autounmask-write<br />
}}<br />
After this, update the config:<br />
{{console|body=(chroot) # ##i##dispatch-conf<br />
}}<br />
Accept the new config by pressing <code>u</code>. Then, you can proceed to install NetworkManager:<br />
<br />
{{console|body=(chroot) # ##i##emerge linux-firmware networkmanager<br />
(chroot) ###i## rc-update add NetworkManager default<br />
}}<br />
The above command will ensure that NetworkManager starts after you boot into Funtoo Linux. Once you've completed these installation steps and have booted into Funtoo Linux, you can use the {{c|nmtui}} command (which has an easy-to-use console-based interface) to configure NetworkManager so that it will connect (and automatically reconnect, after reboot) to a Wi-Fi access point:<br />
{{console|body=# ##i##nmtui}}<br />
For more information about NetworkManager, see the [[Package:NetworkManager|NetworkManager package page]].<br />
<br />
<!--T:234--><br />
{{Note|wpa_supplicant is also a good choice for wireless network connections. See the {{package|net-wireless/wpa_supplicant}} package for steps involved in setting up wpa_supplicant.}}<br />
<br />
==== Desktop (Wired DHCP) ==== <!--T:200--> <br />
<br />
<!--T:201--><br />
For a home desktop or workstation with wired Ethernet that will use DHCP, the simplest and most effective option to enable network connectivity is to simply add {{c|dhcpcd}} to the default runlevel:<br />
<br />
<!--T:203--><br />
{{console|body=<br />
(chroot) # ##i##rc-update add dhcpcd default}}<br />
When you reboot, {{c|dhcpcd}} will run in the background and manage all network interfaces and use DHCP to acquire network addresses from a DHCP server.<br />
<br />
<!--T:204--><br />
If your upstream DHCP server is dnsmasq, it can be configured to assign addresses via mac address to make servers on DHCP feasible.<br />
<br />
==== Server (Static IP) ==== <!--T:205--><br />
<br />
<!--T:235--><br />
For servers, the [[Funtoo Linux Networking]] scripts are recommended. They are optimized for static configurations and things like virtual ethernet bridging for virtualization setups. See [[Funtoo Linux Networking]] for information on how to use Funtoo Linux's template-based network configuration system.<br />
<br />
==== Hostname ==== <!--T:207--><br />
By default Funtoo uses "localhost" as hostname. Although the system will work perfectly fine using this name, some ebuilds refuse to install when detecting localhost as hostname. It also may create confusion if several systems use the same hostname. Therefore, it is advised to change it to a more meaningful name. The hostname itself is arbitrary, meaning you can choose almost any combination of characters, as long as it makes sense to the system administrator. To change the hostname, edit<br />
<br />
<!--T:208--><br />
{{console|body=<br />
(chroot) # ##i##nano /etc/conf.d/hostname<br />
}}<br />
<br />
<!--T:209--><br />
Look for the line starting with hostname and change the entry between the quotes. Save the file, on the next boot Funtoo will use the new hostname.<br />
<br />
<!--T:210--><br />
{{warning|Do not use special characters in the hostname, as the shell may interpret these, leading to unpredictable results. Use the Latin alphabet: a-z, A-Z, 0-9}}<br />
{{tip|Use short hostnames (up to 8 or 10 characters) to prevent the terminal screen being filled with the hostname, leaving little space for the command itself. This become particularly poignant when coding long command strings in various programming languages like Bash, Python, SQL and Perl}}<br />
<br />
=== Finishing Steps === <!--T:211--><br />
==== Set your root password ==== <br />
It's imperative that you set your root password before rebooting so that you can log in.<br />
<console><br />
(chroot) # ##i##passwd<br />
</console><br />
<br />
===Restart your system === <!--T:212--> <br />
<br />
<!--T:213--><br />
Now is the time to leave chroot, to unmount Funtoo Linux partitions and files and to restart your computer. When you restart, the GRUB boot loader will start, load the Linux kernel and initramfs, and your system will begin booting.<br />
<br />
<!--T:214--><br />
Leave the chroot, change directory to /mnt, unmount your Funtoo partitions, and reboot.<br />
<console><br />
(chroot) # ##i##exit<br />
# ##i##cd /mnt<br />
# ##i##umount -lR funtoo<br />
# ##i##reboot<br />
</console><br />
<br />
<!--T:215--><br />
{{fancynote|System Rescue CD will gracefully unmount your new Funtoo filesystems as part of its normal shutdown sequence.}}<br />
<br />
<!--T:216--><br />
You should now see your system reboot, the GRUB boot loader appear for a few seconds, and then see the Linux kernel and initramfs loading. After this, you should see Funtoo Linux itself start to boot, and you should be greeted with a <code>login:</code> prompt. Funtoo Linux has been successfully installed!<br />
<br />
=== Profiles === <!--T:217--> <br />
<br />
<!--T:218--><br />
Once you have rebooted into Funtoo Linux, you can further customize your system to your needs by using [[Funtoo Profiles]]. A quick introduction to profiles is included below -- consult the [[Funtoo Profiles]] page for more detailed information. There are five basic profile types: arch, build, subarch, flavors and mix-ins:<br />
<br />
<!--T:220--><br />
{{TableStart}}<br />
{{2ColHead|Sub-Profile Type|Description}}<br />
{{2Col|{{c|arch}}|Typically {{c|x86-32bit}} or {{c|x86-64bit}}, this defines the processor type and support of your system. This is defined when your stage was built and should not be changed.}}<br />
{{2Col|{{c|build}}|Defines whether your system is a {{c|current}}, {{c|stable}} or {{c|experimental}} build. {{c|current}} systems will have newer packages unmasked than {{c|stable}} systems. This is defined when your stage is built and is typically not changed.}}<br />
{{2Col|{{c|subarch}}|Defines CPU optimizations for your system. The subarch is set at the time the stage3 is built, but can be changed later to better settings if necessary. Be sure to pick a setting that is compatible with your CPU.}}<br />
{{2Col|{{c|flavor}}|Defines the general type of system, such as {{c|server}} or {{c|desktop}}, and will set default USE flags appropriate for your needs.}}<br />
{{2Col|{{c|mix-ins}}|Defines various optional settings that you may be interested in enabling.}}<br />
{{TableEnd}}<br />
<br />
<!--T:221--><br />
One arch, build and flavor must be set for each Funtoo Linux system, while mix-ins are optional and you can enable more than one if desired. Often, flavors and mix-ins inherit settings from other sub-profiles. Use {{c|epro show}} to view your current profile settings, in addition to any inheritance information:</translate><br />
{{console|body=<br />
(chroot) # ##i## epro show<br />
<br />
=== ##g##Enabled Profiles##!g##: ===<br />
<br />
arch: ##c## x86-64bit<br />
build: ##c## current<br />
subarch: ##c## intel64-haswell<br />
flavor: ##c## desktop<br />
mix-ins: ##c## gnome<br />
<br />
<br />
=== ##g##All inherited flavors from desktop flavor##!g##: ===<br />
<br />
##c##workstation##!c## (from desktop flavor)<br />
##c##core##!c## (from workstation flavor)<br />
##c##minimal##!c## (from core flavor)<br />
<br />
=== ##g##All inherited mix-ins from desktop flavor##!g##: ===<br />
<br />
##c##X##!c## (from workstation flavor)<br />
##c##audio##!c## (from workstation flavor)<br />
##c##dvd##!c## (from workstation flavor)<br />
##c##media##!c## (from workstation flavor)<br />
##c##mediadevice-audio-consumer##!c## (from media mix-in)<br />
##c##mediadevice-base##!c## (from mediadevice-audio-consumer mix-in)<br />
##c##mediadevice-video-consumer##!c## (from media mix-in)<br />
##c##mediadevice-base##!c## (from mediadevice-video-consumer mix-in)<br />
##c##mediaformat-audio-common##!c## (from media mix-in)<br />
##c##mediaformat-gfx-common##!c## (from media mix-in)<br />
##c##mediaformat-video-common##!c## (from media mix-in)<br />
##c##console-extras##!c## (from workstation flavor)<br />
##c##print##!c## (from desktop flavor)<br />
}}<br />
<translate><br />
<!--T:223--><br />
Here are some basic examples of {{c|epro}} usage:<br />
{{TableStart}}<br />
{{2ColHead|Description|Command}}<br />
{{2Col|View available profiles. Enabled profiles will be highlighted in cyan. Directly enabled profiles will be in bold and have a {{c|*}} appended.|{{c|epro list}}}}<br />
{{2Col|Change the system flavor.|{{c|epro flavor desktop}}}}<br />
{{2Col|Add a mix-in.|{{c|epro mix-in +gnome}}}}<br />
{{TableEnd}}<br />
<br />
===Next Steps=== <!--T:228--> <br />
<br />
<!--T:229--><br />
If you are brand new to Funtoo Linux and Gentoo Linux, please check out [[Funtoo Linux First Steps]], which will help get you acquainted with your new system. We also have a category for our [[:Category:Official Documentation|official documentation]], which includes all docs that we officially maintain for installation and operation of Funtoo Linux.<br />
<br />
<!--T:230--><br />
We also have a number of pages dedicated to setting up your system. See [[:Category:First Steps|First Steps]] for a list of these pages.<br />
<br />
<!--T:231--><br />
If your system did not boot correctly, see [[Installation Troubleshooting]] for steps you can take to resolve the problem.<br />
<br />
[[Category:HOWTO]]<br />
[[Category:Install]]<br />
[[Category:Official Documentation]]<br />
</translate></div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Power_Monitor&diff=18711Funtoo Power Monitor2017-04-19T02:52:37Z<p>Shamus397: /* Install & Configure Software */</p>
<hr />
<div>= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board =<br />
''N.B.: This page is being fleshed out more as I have more time to devote to it. —Ed''<br />
<br />
Most guides on the internet for doing things like power monitoring on a Raspberry Pi are Debian distro based, and, as such, lack essential things that will make them work on a distro like Funtoo. There is no reason that Funtoo cannot be a first class player in this space, and guides such as these are aimed at alleviating this lack of coverage for Funtoo-based platforms.<br />
<br />
This guide focuses on creating a DC voltage and DC current monitoring system utilizing a Raspberry Pi and the INA219 Current Sensor Breakout board. The INA219 can measure DC voltages up to +32V and DC current up ±3.2A (it can measure higher currents with a different sense resistor). Since dedicated hardware for this kind of monitoring and logging is quite expensive, this combination makes an attractive alternative—not to mention the extreme customizability of this solution.<br />
<br />
{{note|This guide is geared towards Raspberry Pi models that have a 40-pin GPIO header and at least 512MB of RAM; it is also assumed that you have followed the Raspberry Pi on Funtoo installation procedure and have Funtoo up and running on the Pi.}}<br />
<br />
== Basic Outline ==<br />
<br />
* Acquire parts (RPi, INA219, misc. hookup wires, etc)<br />
* Connect parts<br />
* Install & configure software on the RPi<br />
<br />
=== Acquire and Prepare Parts ===<br />
<br />
Obviously, we'll need to acquire a Raspberry Pi, an INA219 breakout board, and various wires to connecting things up. The INA219 comes with a 6 pin header and a 2 pin terminal block that are ''not'' soldered to the board; it's typically easier to deal with hooking things up with those parts soldered in.<br />
<br />
=== Connect Parts ===<br />
<br />
Once we have acquired the INA219 and soldered the headers on it, we can now hook it up to our Raspberry Pi. The basic connections are (pins on the INA219 going from left to right):<br />
<br />
* Vcc goes to pin 4 on the GPIO header<br />
* Gnd goes to pin 6 on the GPIO header<br />
* SCL goes to pin 5 on the GPIO header<br />
* SDA goes to pin 3 on the GPIO header<br />
* A ground line to the RPi will be needed, so connect a wire to pin 9 on the GPIO header<br />
<br />
Connect a wire to Vin+ on the INA219 terminal connector. If you intend to measure current, connect another wire to Vin- on the terminal connector.<br />
<br />
=== Install & Configure Software ===<br />
<br />
Out of the box, the Raspberry Pi disables the I²C bus, so we have to enable it. First, add the following lines to {{c | /boot/config.txt}}:<br />
<br />
{{file | name=/boot/config.txt | desc=Raspberry Pi configuration | body=dtparam=i2c1=on<br />
dtparam=i2c_arm=on}}<br />
<br />
We'll also need to have a module loaded at boot time as well. Add the following to {{c | /etc/conf.d/modules}}:<br />
<br />
{{file | name=/etc/conf.d/modules | desc=I²C module configuration | body=modules="i2c_dev"}}<br />
<br />
Next, we need to install a Python module to read the smbus. The {{c | python}} USE flag should be enabled:<br />
<br />
{{console|body=###i## emerge -avq i2c-tools}}<br />
<br />
Here's where things get messy: we need four more packages (pi_ina219, RPi.GPIO, Adafruit_GPIO, and Adafruit_PureIO) but they aren't in the tree yet. Hopefully by the time this is revised there will be ebuilds for these packages. For now, it's enough to download and install them using their installation methods.<br />
<br />
== Testing ==<br />
<br />
With i2c-tools installed, we can check to see if the RPi can see the INA219 board (use -y 0 for a 256MB RPi):<br />
<br />
{{console|body=###i## i2cdetect -y 1<br />
0 1 2 3 4 5 6 7 8 9 a b c d e f<br />
00: -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
70: -- -- -- -- -- -- -- --}}<br />
<br />
Assuming you didn't change the address of the board (up to four can be connected to the same I²C bus), you should see a 40 in the output. Also, assuming that the i2c_dev module was loaded on boot, you should see an i2c device in /dev:<br />
<br />
{{console|body=###i## ls /dev/i2c*<br />
/dev/i2c-1}}<br />
<br />
For measuring straight DC voltages, all that is needed is to connect the Vin+ wire to the battery positive, and connect the RPi ground (the wire connected to pin 9 on the GPIO header) to the battery negative. If you intend to measure the current consumption of a circuit while powered by the battery being monitored, you will want to connect the Vin- wire to the positive side of the circuit, and RPi ground to the negative side of the circuit.<br />
<br />
{{note|There should be no arcing or sparking anywhere! If there is, '''immediately''' disconnect the offending part, and double check all your connections to make sure that they are correct, and that nothing is shorting out.}}<br />
<br />
Once your circuit is hooked up, you can use the example program in the pi_ina219 package to test that things are working as they should:<br />
<br />
{{console | body=###i## ./example.py<br />
Bus Voltage : 6.384 V<br />
Bus Current : 0.100 mA<br />
Supply Voltage : 6.384 V<br />
Shunt voltage : 0.010 mV<br />
Power : 0.000 mW}}</div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Power_Monitor&diff=18710Funtoo Power Monitor2017-04-19T02:49:30Z<p>Shamus397: /* Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board */</p>
<hr />
<div>= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board =<br />
''N.B.: This page is being fleshed out more as I have more time to devote to it. —Ed''<br />
<br />
Most guides on the internet for doing things like power monitoring on a Raspberry Pi are Debian distro based, and, as such, lack essential things that will make them work on a distro like Funtoo. There is no reason that Funtoo cannot be a first class player in this space, and guides such as these are aimed at alleviating this lack of coverage for Funtoo-based platforms.<br />
<br />
This guide focuses on creating a DC voltage and DC current monitoring system utilizing a Raspberry Pi and the INA219 Current Sensor Breakout board. The INA219 can measure DC voltages up to +32V and DC current up ±3.2A (it can measure higher currents with a different sense resistor). Since dedicated hardware for this kind of monitoring and logging is quite expensive, this combination makes an attractive alternative—not to mention the extreme customizability of this solution.<br />
<br />
{{note|This guide is geared towards Raspberry Pi models that have a 40-pin GPIO header and at least 512MB of RAM; it is also assumed that you have followed the Raspberry Pi on Funtoo installation procedure and have Funtoo up and running on the Pi.}}<br />
<br />
== Basic Outline ==<br />
<br />
* Acquire parts (RPi, INA219, misc. hookup wires, etc)<br />
* Connect parts<br />
* Install & configure software on the RPi<br />
<br />
=== Acquire and Prepare Parts ===<br />
<br />
Obviously, we'll need to acquire a Raspberry Pi, an INA219 breakout board, and various wires to connecting things up. The INA219 comes with a 6 pin header and a 2 pin terminal block that are ''not'' soldered to the board; it's typically easier to deal with hooking things up with those parts soldered in.<br />
<br />
=== Connect Parts ===<br />
<br />
Once we have acquired the INA219 and soldered the headers on it, we can now hook it up to our Raspberry Pi. The basic connections are (pins on the INA219 going from left to right):<br />
<br />
* Vcc goes to pin 4 on the GPIO header<br />
* Gnd goes to pin 6 on the GPIO header<br />
* SCL goes to pin 5 on the GPIO header<br />
* SDA goes to pin 3 on the GPIO header<br />
* A ground line to the RPi will be needed, so connect a wire to pin 9 on the GPIO header<br />
<br />
Connect a wire to Vin+ on the INA219 terminal connector. If you intend to measure current, connect another wire to Vin- on the terminal connector.<br />
<br />
=== Install & Configure Software ===<br />
<br />
Out of the box, the Raspberry Pi disables the I²C bus, so we have to enable it. First, add the following lines to {{c | /boot/config.txt}}:<br />
<br />
{{file | name=/boot/config.txt | desc=Raspberry Pi configuration | body=dtparam=i2c1=on<br />
dtparam=i2c_arm=on}}<br />
<br />
We'll also need to have a module loaded at boot time as well. Add the following to {{c | /etc/conf.d/modules}}:<br />
<br />
{{file | name=/etc/conf.d/modules | desc=I²C module configuration | body=modules="i2c_dev"}}<br />
<br />
Next, we need to install a Python module to read the smbus. The {{c | python}} USE flag should be enabled:<br />
<br />
{{console|body=###i## emerge -avq i2c-tools}}<br />
<br />
Here's where things get messy. We need four more packages (pi_ina219, RPi.GPIO, Adafruit_GPIO, and Adafruit_PureIO) but they aren't in the tree yet. Hopefully by the time this is revised there will be ebuilds for these packages. For now, it's enough to download and install them using their installation methods.<br />
<br />
== Testing ==<br />
<br />
With i2c-tools installed, we can check to see if the RPi can see the INA219 board (use -y 0 for a 256MB RPi):<br />
<br />
{{console|body=###i## i2cdetect -y 1<br />
0 1 2 3 4 5 6 7 8 9 a b c d e f<br />
00: -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
70: -- -- -- -- -- -- -- --}}<br />
<br />
Assuming you didn't change the address of the board (up to four can be connected to the same I²C bus), you should see a 40 in the output. Also, assuming that the i2c_dev module was loaded on boot, you should see an i2c device in /dev:<br />
<br />
{{console|body=###i## ls /dev/i2c*<br />
/dev/i2c-1}}<br />
<br />
For measuring straight DC voltages, all that is needed is to connect the Vin+ wire to the battery positive, and connect the RPi ground (the wire connected to pin 9 on the GPIO header) to the battery negative. If you intend to measure the current consumption of a circuit while powered by the battery being monitored, you will want to connect the Vin- wire to the positive side of the circuit, and RPi ground to the negative side of the circuit.<br />
<br />
{{note|There should be no arcing or sparking anywhere! If there is, '''immediately''' disconnect the offending part, and double check all your connections to make sure that they are correct, and that nothing is shorting out.}}<br />
<br />
Once your circuit is hooked up, you can use the example program in the pi_ina219 package to test that things are working as they should:<br />
<br />
{{console | body=###i## ./example.py<br />
Bus Voltage : 6.384 V<br />
Bus Current : 0.100 mA<br />
Supply Voltage : 6.384 V<br />
Shunt voltage : 0.010 mV<br />
Power : 0.000 mW}}</div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Power_Monitor&diff=18709Funtoo Power Monitor2017-04-19T02:45:50Z<p>Shamus397: /* Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board */</p>
<hr />
<div>= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board =<br />
''N.B.: This page is being fleshed out more as I have more time to devote to it. —Ed''<br />
<br />
Most guides on the internet for doing things like power monitoring on a Raspberry Pi are Debian distro based, and, as such, lack essential things that will make them work on a distro like Funtoo. There is no reason that Funtoo cannot be a first class player in this space, and guides such as these are aimed at alleviating this lack of coverage for Funtoo-based platforms.<br />
<br />
This guide focuses on creating a DC voltage and DC current monitoring system utilizing a Raspberry Pi and the INA219 Current Sensor Breakout board. The INA219 can measure DC voltages up to +32V and DC current up ±3.2A (it can measure higher currents with a different sense resistor). Since dedicated hardware for this kind of monitoring and logging is quite expensive, this combination makes an attractive alternative—not to mention the extreme customizability of this solution.<br />
<br />
{{note|This guide is geared towards Raspberry Pi models that have a 40-pin GPIO header and at least 512MB of RAM.}}<br />
<br />
== Basic Outline ==<br />
<br />
* Acquire parts (RPi, INA219, misc. hookup wires, etc)<br />
* Connect parts<br />
* Install & configure software on the RPi<br />
<br />
=== Acquire and Prepare Parts ===<br />
<br />
Obviously, we'll need to acquire a Raspberry Pi, an INA219 breakout board, and various wires to connecting things up. The INA219 comes with a 6 pin header and a 2 pin terminal block that are ''not'' soldered to the board; it's typically easier to deal with hooking things up with those parts soldered in.<br />
<br />
=== Connect Parts ===<br />
<br />
Once we have acquired the INA219 and soldered the headers on it, we can now hook it up to our Raspberry Pi. The basic connections are (pins on the INA219 going from left to right):<br />
<br />
* Vcc goes to pin 4 on the GPIO header<br />
* Gnd goes to pin 6 on the GPIO header<br />
* SCL goes to pin 5 on the GPIO header<br />
* SDA goes to pin 3 on the GPIO header<br />
* A ground line to the RPi will be needed, so connect a wire to pin 9 on the GPIO header<br />
<br />
Connect a wire to Vin+ on the INA219 terminal connector. If you intend to measure current, connect another wire to Vin- on the terminal connector.<br />
<br />
=== Install & Configure Software ===<br />
<br />
Out of the box, the Raspberry Pi disables the I²C bus, so we have to enable it. First, add the following lines to {{c | /boot/config.txt}}:<br />
<br />
{{file | name=/boot/config.txt | desc=Raspberry Pi configuration | body=dtparam=i2c1=on<br />
dtparam=i2c_arm=on}}<br />
<br />
We'll also need to have a module loaded at boot time as well. Add the following to {{c | /etc/conf.d/modules}}:<br />
<br />
{{file | name=/etc/conf.d/modules | desc=I²C module configuration | body=modules="i2c_dev"}}<br />
<br />
Next, we need to install a Python module to read the smbus. The {{c | python}} USE flag should be enabled:<br />
<br />
{{console|body=###i## emerge -avq i2c-tools}}<br />
<br />
Here's where things get messy. We need four more packages (pi_ina219, RPi.GPIO, Adafruit_GPIO, and Adafruit_PureIO) but they aren't in the tree yet. Hopefully by the time this is revised there will be ebuilds for these packages. For now, it's enough to download and install them using their installation methods.<br />
<br />
== Testing ==<br />
<br />
With i2c-tools installed, we can check to see if the RPi can see the INA219 board (use -y 0 for a 256MB RPi):<br />
<br />
{{console|body=###i## i2cdetect -y 1<br />
0 1 2 3 4 5 6 7 8 9 a b c d e f<br />
00: -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
70: -- -- -- -- -- -- -- --}}<br />
<br />
Assuming you didn't change the address of the board (up to four can be connected to the same I²C bus), you should see a 40 in the output. Also, assuming that the i2c_dev module was loaded on boot, you should see an i2c device in /dev:<br />
<br />
{{console|body=###i## ls /dev/i2c*<br />
/dev/i2c-1}}<br />
<br />
For measuring straight DC voltages, all that is needed is to connect the Vin+ wire to the battery positive, and connect the RPi ground (the wire connected to pin 9 on the GPIO header) to the battery negative. If you intend to measure the current consumption of a circuit while powered by the battery being monitored, you will want to connect the Vin- wire to the positive side of the circuit, and RPi ground to the negative side of the circuit.<br />
<br />
{{note|There should be no arcing or sparking anywhere! If there is, '''immediately''' disconnect the offending part, and double check all your connections to make sure that they are correct, and that nothing is shorting out.}}<br />
<br />
Once your circuit is hooked up, you can use the example program in the pi_ina219 package to test that things are working as they should:<br />
<br />
{{console | body=###i## ./example.py<br />
Bus Voltage : 6.384 V<br />
Bus Current : 0.100 mA<br />
Supply Voltage : 6.384 V<br />
Shunt voltage : 0.010 mV<br />
Power : 0.000 mW}}</div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Power_Monitor&diff=18708Funtoo Power Monitor2017-04-19T02:20:58Z<p>Shamus397: /* Connect Parts */</p>
<hr />
<div>= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board =<br />
''N.B.: This page is mostly a placeholder with the big picture items spelled out. I will flesh it out more as I have more time to devote to it. —Ed''<br />
<br />
Most guides on the internet for doing things like power monitoring on a Raspberry Pi are Debian distro based, and, as such, lack essential things that will make them work on a distro like Funtoo. This guide focuses on creating a DC voltage and DC current monitoring system utilizing the INA219 Current Sensor Breakout board.<br />
<br />
The INA219 can measure DC voltages up to +32V and DC current up ±3.2A (it can measure higher currents with a different sense resistor).<br />
<br />
== Basic Outline ==<br />
<br />
* Acquire parts (RPi, INA219, misc. hookup wires, etc)<br />
* Connect parts<br />
* Install & configure software on the RPi<br />
<br />
=== Acquire Parts ===<br />
<br />
Obviously, we'll need to acquire a Raspberry Pi, an INA219 breakout board, and various wires to connecting things up.<br />
<br />
=== Connect Parts ===<br />
<br />
Once we have acquired the INA219 and soldered the headers on it, we can now hook it up to our Raspberry Pi. The basic connections are (pins on the INA219 going from left to right):<br />
<br />
* Vcc goes to pin 4 on the GPIO header<br />
* Gnd goes to pin 6 on the GPIO header<br />
* SCL goes to pin 5 on the GPIO header<br />
* SDA goes to pin 3 on the GPIO header<br />
* A ground line to the RPi will be needed, so connect a wire to pin 9 on the GPIO header<br />
<br />
Connect a wire to Vin+ on the INA219 terminal connector. If you intend to measure current, connect another wire to Vin- on the terminal connector.<br />
<br />
=== Install & Configure Software ===<br />
<br />
Out of the box, the Raspberry Pi disables the I²C bus, so we have to enable it. First, add the following lines to {{c | /boot/config.txt}}:<br />
<br />
{{file | name=/boot/config.txt | desc=Raspberry Pi configuration | body=dtparam=i2c1=on<br />
dtparam=i2c_arm=on}}<br />
<br />
We'll also need to have a module loaded at boot time as well. Add the following to {{c | /etc/conf.d/modules}}:<br />
<br />
{{file | name=/etc/conf.d/modules | desc=I²C module configuration | body=modules="i2c_dev"}}<br />
<br />
Next, we need to install a Python module to read the smbus. The {{c | python}} USE flag should be enabled:<br />
<br />
{{console|body=###i## emerge -avq i2c-tools}}<br />
<br />
Here's where things get messy. We need four more packages (pi_ina219, RPi.GPIO, Adafruit_GPIO, and Adafruit_PureIO) but they aren't in the tree yet. Hopefully by the time this is revised there will be ebuilds for these packages. For now, it's enough to download and install them using their installation methods.<br />
<br />
== Testing ==<br />
<br />
With i2c-tools installed, we can check to see if the RPi can see the INA219 board (use -y 0 for a 256MB RPi):<br />
<br />
{{console|body=###i## i2cdetect -y 1<br />
0 1 2 3 4 5 6 7 8 9 a b c d e f<br />
00: -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
70: -- -- -- -- -- -- -- --}}<br />
<br />
Assuming you didn't change the address of the board (up to four can be connected to the same I²C bus), you should see a 40 in the output. Also, assuming that the i2c_dev module was loaded on boot, you should see an i2c device in /dev:<br />
<br />
{{console|body=###i## ls /dev/i2c*<br />
/dev/i2c-1}}<br />
<br />
For measuring straight DC voltages, all that is needed is to connect the Vin+ wire to the battery positive, and connect the RPi ground (the wire connected to pin 9 on the GPIO header) to the battery negative. If you intend to measure the current consumption of a circuit while powered by the battery being monitored, you will want to connect the Vin- wire to the positive side of the circuit, and RPi ground to the negative side of the circuit.<br />
<br />
{{note|There should be no arcing or sparking anywhere! If there is, '''immediately''' disconnect the offending part, and double check all your connections to make sure that they are correct, and that nothing is shorting out.}}<br />
<br />
Once your circuit is hooked up, you can use the example program in the pi_ina219 package to test that things are working as they should:<br />
<br />
{{console | body=###i## ./example.py<br />
Bus Voltage : 6.384 V<br />
Bus Current : 0.100 mA<br />
Supply Voltage : 6.384 V<br />
Shunt voltage : 0.010 mV<br />
Power : 0.000 mW}}</div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Power_Monitor&diff=18706Funtoo Power Monitor2017-04-18T17:14:05Z<p>Shamus397: Created page with "= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board = ''N.B.: This page is mostly a placeholder with the big picture it..."</p>
<hr />
<div>= Making a Funtoo Based DC Voltage/Current Monitoring System Using a Raspberry Pi and INA219 Breakout Board =<br />
''N.B.: This page is mostly a placeholder with the big picture items spelled out. I will flesh it out more as I have more time to devote to it. —Ed''<br />
<br />
Most guides on the internet for doing things like power monitoring on a Raspberry Pi are Debian distro based, and, as such, lack essential things that will make them work on a distro like Funtoo. This guide focuses on creating a DC voltage and DC current monitoring system utilizing the INA219 Current Sensor Breakout board.<br />
<br />
The INA219 can measure DC voltages up to +32V and DC current up ±3.2A (it can measure higher currents with a different sense resistor).<br />
<br />
== Basic Outline ==<br />
<br />
* Acquire parts (RPi, INA219, misc. hookup wires, etc)<br />
* Connect parts<br />
* Install & configure software on the RPi<br />
<br />
=== Acquire Parts ===<br />
<br />
Obviously, we'll need to acquire a Raspberry Pi, an INA219 breakout board, and various wires to connecting things up.<br />
<br />
=== Connect Parts ===<br />
<br />
Once we have acquired the INA219 and soldered the headers on it, we can now hook it up to our Raspberry Pi. The basic connections are (pins on the INA219 going from left to right):<br />
<br />
* Vcc goes to pin 4 on the GPIO header<br />
* Gnd goes to pin 6 on the GPIO header<br />
* SCL goes to pin 3 on the GPIO header<br />
* SDA goes to pin 5 on the GPIO header<br />
* A ground line to the RPi will be needed, so connect a wire to pin 9 on the GPIO header<br />
<br />
Connect a wire to Vin+ on the INA219 terminal connector. If you intend to measure current, connect another wire to Vin- on the terminal connector.<br />
<br />
=== Install & Configure Software ===<br />
<br />
Out of the box, the Raspberry Pi disables the I²C bus, so we have to enable it. First, add the following lines to {{c | /boot/config.txt}}:<br />
<br />
{{file | name=/boot/config.txt | desc=Raspberry Pi configuration | body=dtparam=i2c1=on<br />
dtparam=i2c_arm=on}}<br />
<br />
We'll also need to have a module loaded at boot time as well. Add the following to {{c | /etc/conf.d/modules}}:<br />
<br />
{{file | name=/etc/conf.d/modules | desc=I²C module configuration | body=modules="i2c_dev"}}<br />
<br />
Next, we need to install a Python module to read the smbus. The {{c | python}} USE flag should be enabled:<br />
<br />
{{console|body=###i## emerge -avq i2c-tools}}<br />
<br />
Here's where things get messy. We need four more packages (pi_ina219, RPi.GPIO, Adafruit_GPIO, and Adafruit_PureIO) but they aren't in the tree yet. Hopefully by the time this is revised there will be ebuilds for these packages. For now, it's enough to download and install them using their installation methods.<br />
<br />
== Testing ==<br />
<br />
With i2c-tools installed, we can check to see if the RPi can see the INA219 board (use -y 0 for a 256MB RPi):<br />
<br />
{{console|body=###i## i2cdetect -y 1<br />
0 1 2 3 4 5 6 7 8 9 a b c d e f<br />
00: -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- <br />
70: -- -- -- -- -- -- -- --}}<br />
<br />
Assuming you didn't change the address of the board (up to four can be connected to the same I²C bus), you should see a 40 in the output. Also, assuming that the i2c_dev module was loaded on boot, you should see an i2c device in /dev:<br />
<br />
{{console|body=###i## ls /dev/i2c*<br />
/dev/i2c-1}}<br />
<br />
For measuring straight DC voltages, all that is needed is to connect the Vin+ wire to the battery positive, and connect the RPi ground (the wire connected to pin 9 on the GPIO header) to the battery negative. If you intend to measure the current consumption of a circuit while powered by the battery being monitored, you will want to connect the Vin- wire to the positive side of the circuit, and RPi ground to the negative side of the circuit.<br />
<br />
{{note|There should be no arcing or sparking anywhere! If there is, '''immediately''' disconnect the offending part, and double check all your connections to make sure that they are correct, and that nothing is shorting out.}}<br />
<br />
Once your circuit is hooked up, you can use the example program in the pi_ina219 package to test that things are working as they should:<br />
<br />
{{console | body=###i## ./example.py<br />
Bus Voltage : 6.384 V<br />
Bus Current : 0.100 mA<br />
Supply Voltage : 6.384 V<br />
Shunt voltage : 0.010 mV<br />
Power : 0.000 mW}}</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17196Mail Server2016-12-20T15:34:43Z<p>Shamus397: /* Configuring Postfix */ added more clarification, a few missing things</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl mysql pam ssl<br />
net-mail/dovecot bzip2 maildir mysql pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom of {{f|/etc/postfix/main.cf}}:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (we will be changing the defaults in the file to what's shown here). Since this is a new install, the developers recommended that the {{c|compatibility_level}} be set to 2:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
}}<br />
<br />
Next, we will be setting up the mail server's hostname and domain. How we fill this in depends on what your DNS and MX records point to. If you have it set up so that your main domain is of the form ''tld.ext'', then you will put that into the {{c|mydomain}} field, otherwise, you will set it the same as the {{c|myshostname}} field (in ''host.tld.ext'' form):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
myhostname = <my.fqdn.com><br />
mydomain = <fqdn.com {{!}} my.fqdn.com><br />
}}<br />
<br />
The {{c|mydestination}} field '''MUST''' be set to localhost, otherwise, incoming mail will bounce:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mydestination = localhost # This MUST be set to localhost<br />
}}<br />
<br />
Some mail servers will not talk to you if the hostname that is set up on your reverse DNS record does not match the SMTP banner that Postfix sends to peers. To fix that, add the following (replace ''<reverse DNS hostname>'' with your real reverse DNS hostname):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=And yet more Postfix configuration|body=<br />
smtpd_banner = <reverse DNS hostname> ESMTP $mail_name<br />
}}<br />
<br />
{{note|It is not necessary for the reverse DNS hostname to match your mail server's hostname; it just has to be present.}}<br />
<br />
Finally, in this file, we have to enumerate the networks that can relay mail via our server. Generally we want to list ''only'' the subnets that we want to be able to send mail from (replace ''<LAN IP>'' with your LAN's subnet and ''<LAN netmask>'' with your LAN's netmask, and leave 127.0.0.0/8 in):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mynetworks = <LAN IP>/<LAN netmask>, 127.0.0.0/8<br />
}}<br />
<br />
{{note|If you want one or more remote hosts to be able to send through your mail server, you should add them to the {{c|mynetworks}} line as comma separated values. Also, you should set the netmask (the part after the '/') on each of them to 32, to ensure that ''only'' those IP addresses can be sent from.}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
If we want Postfix to talk on port 25, we have to make sure that the second field in the line in {{f|/etc/postfix/master.cf}} for smtp is {{c|inet}}:<br />
<br />
{{file|name=/etc/postfix/master.cf|desc=Postfix master service file|body=<br />
# ==========================================================================<br />
# service type private unpriv chroot wakeup maxproc command + args<br />
# (yes) (yes) (no) (never) (100)<br />
# ==========================================================================<br />
smtp inet n - y - - smtpd<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}. We need to tell Dovecot where to store mail (and, in the case of IMAP, keep it). {{c|mail_location}} and {{c|mail_privileged_group}} will likely be in there already and need to be changed; we will likely have to add {{c|first_valid_uid}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/conf.d/10-auth.conf}}: Here we have to tell Dovecot how we want to authenticate our users. Note that in addition to setting {{c|disable_plaintext_auth}} to ''yes'' and {{c|auth_mechanisms}} to ''plain login'', we need to comment out (by inserting a '#' in front of) the line {{c|!include auth-system.conf.ext}} and uncomment (by removing any '#' in front of) the line {{c|!include auth-sql.conf.ext}}. This is to prevent Dovecot from using native accounts for authorization and use our database instead:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#!include auth-system.conf.ext<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
Next we need to edit {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}, so Dovecot knows where and how the passwords are stored, and how and where to write our users' mail:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/dovecot-sql.conf.ext}}, which is mentioned in the previous file. This is to tell Dovecot the details of how to talk to the database in order to validate user logins (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next file we have to modify is {{f|/etc/dovecot/conf.d/10-master.conf}}. First, we will set the listener ports for IMAP and POP3 to zero, to force encrypted links:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
}}<br />
<br />
Next, we have to configure Dovecot's LMTP service:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
}}<br />
<br />
Finally, we need to properly set up the {{c|auth}} and {{c|auth-worker}} services:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, we need to edit {{f|/etc/dovecot/conf.d/10-ssl.conf}}, so that Dovecot knows where to find valid certificates to work with:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, the certificates generated this way are self-signed; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17194Mail Server2016-12-18T16:14:36Z<p>Shamus397: /* Preparation */ add missing USE flag</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl mysql pam ssl<br />
net-mail/dovecot bzip2 maildir mysql pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (we will be changing the defaults in the file to what's shown here). Since this is a new install, the developers recommended that the {{c|compatibility_level}} be set to 2:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
}}<br />
<br />
Next, we will be setting up the mail server's hostname and domain. How we fill this in depends on what your DNS and MX records point to. If you have it set up so that your main domain is of the form ''tld.ext'', then you will put that into the {{c|mydomain}} field, otherwise, you will set it the same as the {{c|myshostname}} field (in ''host.tld.ext'' form):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
myhostname = <my.fqdn.com><br />
mydomain = <fqdn.com {{!}} my.fqdn.com><br />
}}<br />
<br />
The {{c|mydestination}} field '''MUST''' be set to localhost, otherwise, incoming mail will bounce:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mydestination = localhost # This MUST be set to localhost<br />
}}<br />
<br />
Finally, in this file, we have to enumerate the networks that can relay mail via our server. Generally we want to list ''only'' the subnets that we want to be able to send mail from (replace ''<LAN IP>'' with your LAN's subnet and ''<LAN netmask>'' with your LAN's netmask, and leave 127.0.0.0/8 in):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mynetworks = <LAN IP>/<LAN netmask>, 127.0.0.0/8<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}. We need to tell Dovecot where to store mail (and, in the case of IMAP, keep it). {{c|mail_location}} and {{c|mail_privileged_group}} will likely be in there already and need to be changed; we will likely have to add {{c|first_valid_uid}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/conf.d/10-auth.conf}}: Here we have to tell Dovecot how we want to authenticate our users. Note that in addition to setting {{c|disable_plaintext_auth}} to ''yes'' and {{c|auth_mechanisms}} to ''plain login'', we need to comment out (by inserting a '#' in front of) the line {{c|!include auth-system.conf.ext}} and uncomment (by removing any '#' in front of) the line {{c|!include auth-sql.conf.ext}}. This is to prevent Dovecot from using native accounts for authorization and use our database instead:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#!include auth-system.conf.ext<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
Next we need to edit {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}, so Dovecot knows where and how the passwords are stored, and how and where to write our users' mail:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/dovecot-sql.conf.ext}}, which is mentioned in the previous file. This is to tell Dovecot the details of how to talk to the database in order to validate user logins (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next file we have to modify is {{f|/etc/dovecot/conf.d/10-master.conf}}. First, we will set the listener ports for IMAP and POP3 to zero, to force encrypted links:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
}}<br />
<br />
Next, we have to configure Dovecot's LMTP service:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
}}<br />
<br />
Finally, we need to properly set up the {{c|auth}} and {{c|auth-worker}} services:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, we need to edit {{f|/etc/dovecot/conf.d/10-ssl.conf}}, so that Dovecot knows where to find valid certificates to work with:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, the certificates generated this way are self-signed; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17193Mail Server2016-12-15T01:33:31Z<p>Shamus397: /* Configuring Dovecot */ expanding the explanations</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (we will be changing the defaults in the file to what's shown here). Since this is a new install, the developers recommended that the {{c|compatibility_level}} be set to 2:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
}}<br />
<br />
Next, we will be setting up the mail server's hostname and domain. How we fill this in depends on what your DNS and MX records point to. If you have it set up so that your main domain is of the form ''tld.ext'', then you will put that into the {{c|mydomain}} field, otherwise, you will set it the same as the {{c|myshostname}} field (in ''host.tld.ext'' form):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
myhostname = <my.fqdn.com><br />
mydomain = <fqdn.com {{!}} my.fqdn.com><br />
}}<br />
<br />
The {{c|mydestination}} field '''MUST''' be set to localhost, otherwise, incoming mail will bounce:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mydestination = localhost # This MUST be set to localhost<br />
}}<br />
<br />
Finally, in this file, we have to enumerate the networks that can relay mail via our server. Generally we want to list ''only'' the subnets that we want to be able to send mail from (replace ''<LAN IP>'' with your LAN's subnet and ''<LAN netmask>'' with your LAN's netmask, and leave 127.0.0.0/8 in):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mynetworks = <LAN IP>/<LAN netmask>, 127.0.0.0/8<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}. We need to tell Dovecot where to store mail (and, in the case of IMAP, keep it). {{c|mail_location}} and {{c|mail_privileged_group}} will likely be in there already and need to be changed; we will likely have to add {{c|first_valid_uid}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/conf.d/10-auth.conf}}: Here we have to tell Dovecot how we want to authenticate our users. Note that in addition to setting {{c|disable_plaintext_auth}} to ''yes'' and {{c|auth_mechanisms}} to ''plain login'', we need to comment out (by inserting a '#' in front of) the line {{c|!include auth-system.conf.ext}} and uncomment (by removing any '#' in front of) the line {{c|!include auth-sql.conf.ext}}. This is to prevent Dovecot from using native accounts for authorization and use our database instead:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#!include auth-system.conf.ext<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
Next we need to edit {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}, so Dovecot knows where and how the passwords are stored, and how and where to write our users' mail:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
Next is {{f|/etc/dovecot/dovecot-sql.conf.ext}}, which is mentioned in the previous file. This is to tell Dovecot the details of how to talk to the database in order to validate user logins (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next file we have to modify is {{f|/etc/dovecot/conf.d/10-master.conf}}. First, we will set the listener ports for IMAP and POP3 to zero, to force encrypted links:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
}}<br />
<br />
Next, we have to configure Dovecot's LMTP service:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
}}<br />
<br />
Finally, we need to properly set up the {{c|auth}} and {{c|auth-worker}} services:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, we need to edit {{f|/etc/dovecot/conf.d/10-ssl.conf}}, so that Dovecot knows where to find valid certificates to work with:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, the certificates generated this way are self-signed; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17192Mail Server2016-12-15T00:43:47Z<p>Shamus397: /* Configuring Postfix */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (we will be changing the defaults in the file to what's shown here). Since this is a new install, the developers recommended that the {{c|compatibility_level}} be set to 2:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
}}<br />
<br />
Next, we will be setting up the mail server's hostname and domain. How we fill this in depends on what your DNS and MX records point to. If you have it set up so that your main domain is of the form ''tld.ext'', then you will put that into the {{c|mydomain}} field, otherwise, you will set it the same as the {{c|myshostname}} field (in ''host.tld.ext'' form):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
myhostname = <my.fqdn.com><br />
mydomain = <fqdn.com {{!}} my.fqdn.com><br />
}}<br />
<br />
The {{c|mydestination}} field '''MUST''' be set to localhost, otherwise, incoming mail will bounce:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mydestination = localhost # This MUST be set to localhost<br />
}}<br />
<br />
Finally, in this file, we have to enumerate the networks that can relay mail via our server. Generally we want to list ''only'' the subnets that we want to be able to send mail from (replace ''<LAN IP>'' with your LAN's subnet and ''<LAN netmask>'' with your LAN's netmask, and leave 127.0.0.0/8 in):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
mynetworks = <LAN IP>/<LAN netmask>, 127.0.0.0/8<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}} (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17191Mail Server2016-12-14T17:56:18Z<p>Shamus397: /* Configuring Postfix */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}} (be sure to replace ''<mailuserpass>'' with mailuser's real password):<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = <mailuserpass><br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}} (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17190Mail Server2016-12-14T05:11:38Z<p>Shamus397: /* Setting up the Database */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT} }} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}} (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17189Mail Server2016-12-14T05:05:47Z<p>Shamus397: /* Client Configuration */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}} (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm that you want to use the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17188Mail Server2016-12-14T05:02:03Z<p>Shamus397: /* Configuring Dovecot */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}} (replace ''<mailuserpass>'' with the password you created for the MySQL user 'mailuser'):<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=<mailuserpass><br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17187Mail Server2016-12-14T04:59:51Z<p>Shamus397: /* Configuring Dovecot */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/mailstore/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/mailstore/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17186Mail Server2016-12-14T04:51:09Z<p>Shamus397: /* Final Steps */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/decrypted-mail/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/decrypted-mail/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17185Mail Server2016-12-14T04:42:53Z<p>Shamus397: </p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__FORCETOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/decrypted-mail/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/decrypted-mail/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Postfix and Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17184Mail Server2016-12-14T04:42:23Z<p>Shamus397: Still needs work, but that's enough for tonight</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
___FORCETOC___<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. It is also essential for reliable mail delivery to have properly-configured ''reverse DNS'' as many mail servers will use reverse DNS and will expect your IP address to resolve to your advertised hostname. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/decrypted-mail/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/decrypted-mail/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Postfix and Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
With that, the mail server should be configured correctly to send and receive email. If it doesn't work, you will probably want to snoop around {{f|/var/log/messages}} and look for lines that have {{c|postfix}} or {{c|dovecot}} in them for clues.<br />
<br />
== Client Configuration ==<br />
<br />
This configuration is for Thunderbird, but it should be applicable to any other client. When setting up a new account, it will ask for your name, email address, and password. Clicking on the {{c|Continue}} button will then have Thunderbird attempt to autodetect your mail server settings automagically; this should normally fail (if not, then you're done!). If you look in {{f|/var/log/messages}} on the mail server, you should see something similar to this:<br />
<br />
{{file|name=/var/log/messages|desc=System log file|body=<br />
postfix/smtpd[]: improper command pipelining after EHLO from <client FQDN>[<client IP>]: QUIT\r\n<br />
}}<br />
<br />
The solution then is to select port 993 from the {{c|Port:}} combobox on the {{C|Incoming:}} line. Hitting the {{c|Re-test}} button should allow Thunderbird to properly detect the settings at this point, assuming that the following is true:<br />
<br />
* The server hostname fields contain the FQDN of your mail server<br />
* The {{c|Incoming:}} and {{c|Outgoing:}} username fields contain the user's full email address<br />
* The password given for the user's email address is correct.<br />
<br />
If all else fails, you can try the following settings:<br />
<br />
{{TableStart}}<br />
<tr class="info"><th></th><th>Protocol</th><th>Server</th><th>Port</th><th>SSL</th><th>Authentication</th></tr><br />
<tr><td>Incoming:</td><td>IMAP</td><td>''mail server's FQDN''</td><td>993</td><td>SSL/TLS</td><td>Normal password</td></tr><br />
<tr><td>Outgoing:</td><td>SMTP</td><td>''mail server's FQDN''</td><td>25</td><td>STARTTLS</td><td>Normal password</td></tr><br />
{{TableEnd}}<br />
<br />
{{note|Once the settings are correct in Thunderbird, the first time you send or receive an email message, Thunderbird will ask you to confirm the certificates coming from your email server if they are self-signed.}}<br />
<br />
== A Few Words on Security, Spam & Blacklists ==<br />
<br />
The email server you have just set up should be reasonably secure from attackers; it won't relay messages outside of your LAN and it won't talk to unencrypted peers. As long as you and your users have chosen good, strong passwords for each link of the chain, you shouldn't have to worry too much about such as bad actors, or being put on spam blacklists. As long as you keep an eye on your mail server and investigate suspicious activity, it should serve you well and work well in the wider Internet environment.<br />
<br />
== But Wait, There's More! ==<br />
<br />
But only a bit more. Those are the basics, but if you want you can also set up SPF, DKIM, PTR records; unfortunately those are beyond the scope of this article. Other possibilities are spam filtering, push support, and full text-search; these are left as an exercise for the reader.</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17182Mail Server2016-12-14T03:28:32Z<p>Shamus397: /* Final Steps */</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
___TOC___<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/decrypted-mail/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/decrypted-mail/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Postfix and Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###i## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
== Client Configuration ==<br />
<br />
<br />
<br />
== Success! ==</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17181Mail Server2016-12-14T03:23:51Z<p>Shamus397: </p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
___TOC___<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
Next, we need to set up the location on the server where email will be delivered:<br />
<br />
{{console|body=<br />
###i## mkdir /mailstore<br />
###i## chgrp mail /mailstore<br />
###i## chmod -R g+rw /mailstore<br />
}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
=== Configuring Postfix ===<br />
<br />
Now we have to configure Postfix. Pull up your favorite text editor and add the following lines to the bottom:<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=Postfix configuration|body=<br />
# SASL config<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = private/auth<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
<br />
# TLS config<br />
smtpd_tls_cert_file = /etc/ssl/certs/dovecot.pem<br />
smtpd_tls_key_file = /etc/ssl/private/dovecot.pem<br />
smtpd_use_tls = yes<br />
smtpd_tls_auth_only = yes<br />
smtp_tls_security_level = may<br />
smtp_tls_loglevel = 2<br />
smtpd_tls_received_header = yes<br />
<br />
# Authentication config<br />
virtual_transport = lmtp:unix:private/dovecot-lmtp<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
virtual_alias_maps = mysql:/etc/postfix/mysql-virtual-alias-maps.cf<br />
local_recipient_maps = $virtual_mailbox_maps<br />
}}<br />
<br />
Next, we have to change a few items in the same config file (change the defaults in the file to what's listed here):<br />
<br />
{{file|name=/etc/postfix/main.cf|desc=More Postfix configuration|body=<br />
compatibility_level = 2<br />
myhostname = <my.fqdn.com> # Replace <my.fqdn.com> with your mail server's FQDN<br />
mydomain = <fqdn.com> # Replace <fqdn.com> with your mail server's domain<br />
mydestination = localhost # This MUST be set to localhost<br />
mynetworks = 192.168.0.0/24, 127.0.0.0/8 # Replace 192.168.0.0/24 with your LAN's IP/mask<br />
}}<br />
<br />
Next, we have to create the files referenced above as part of the 'Authentication config'. First, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-domains.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-domains.cf|desc=MySQL/virtual domains Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_domains WHERE name='%s'<br />
}}<br />
<br />
Next, we have to create {{f|/etc/postfix/mysql-virtual-mailbox-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-mailbox-maps.cf|desc=MySQL/virtual maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT 1 FROM virtual_users WHERE email='%s'<br />
}}<br />
<br />
And finally, we have to create {{f|/etc/postfix/mysql-virtual-alias-maps.cf}}:<br />
<br />
{{file|name=/etc/postfix/mysql-virtual-alias-maps.cf|desc=MySQL/virtual alias maps Postfix configuration|body=<br />
user = mailuser<br />
password = mailuserpass<br />
hosts = 127.0.0.1<br />
dbname = mailserver<br />
query = SELECT destination FROM virtual_aliases WHERE source='%s'<br />
}}<br />
<br />
Now lets start Postfix and make sure that our authentication queries are working:<br />
<br />
{{console|body=<br />
###i## /etc/init.d/postfix start<br />
###i## postmap -q <my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-domains.cf<br />
1<br />
###i## postmap -q <user>@<my.fqdn.com> mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf<br />
1<br />
}}<br />
<br />
Assuming both {{c|postmap}} commands returned 1, we can go on to configuring Dovecot.<br />
<br />
=== Configuring Dovecot ===<br />
<br />
Now that Postfix is properly configured, it's time to tackle Dovecot. The first file we want to look at is {{f|/etc/dovecot/dovecot.conf}}. In particular, we want to make sure the {{c|protocols}} line has {{c|imap}}, {{c|pop3}}, and {{c|lmtp}} enabled:<br />
<br />
{{file|name=/etc/dovecot/dovecot.conf|desc=Dovecot configuration|body=<br />
protocols = imap pop3 lmtp<br />
}}<br />
<br />
Next we need to look at {{f|/etc/dovecot/conf.d/10-mail.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-mail.conf|desc=Dovecot configuration|body=<br />
mail_location = maildir:/decrypted-mail/%d/%n<br />
mail_privileged_group = mail<br />
first_valid_uid = 0<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/10-auth.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-auth.conf|desc=Dovecot authorization config|body=<br />
disable_plaintext_auth = yes<br />
auth_mechanisms = plain login<br />
#INSERT a hashtag in front of the following import. This separates your mail server's login from UNIX logins.<br />
#!include auth-system.conf.ext<br />
#REMOVE the hashtag in front of the following import. This points it at mysql for authentication.<br />
!include auth-sql.conf.ext<br />
}}<br />
<br />
On to {{f|/etc/dovecot/conf.d/auth-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/auth-sql.conf.ext|desc=Dovecot SQL config|body=<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf.ext<br />
}<br />
userdb {<br />
driver = static<br />
args = uid=mail gid=mail home=/decrypted-mail/%d/%n<br />
}<br />
}}<br />
<br />
On to {{f|/etc/dovecot/dovecot-sql.conf.ext}}:<br />
<br />
{{file|name=/etc/dovecot/dovecot-sql.conf.ext|desc=More Dovecot SQL config|body=<br />
driver = mysql<br />
connect = host=127.0.0.1 dbname=mailserver user=mailuser password=mailuserpass<br />
default_pass_scheme = SHA512-CRYPT<br />
password_query = SELECT email as user, password FROM virtual_users WHERE email='%u';<br />
}}<br />
<br />
Next up is {{f|/etc/dovecot/conf.d/10-master.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-master.conf|desc=Dovecot master config file|body=<br />
service imap-login {<br />
inet_listener imap {<br />
port = 0<br />
}<br />
…<br />
service pop3-login {<br />
inet_listener pop3 {<br />
port = 0<br />
}<br />
…<br />
service lmtp {<br />
unix_listener /var/spool/postfix/private/dovecot-lmtp {<br />
mode = 0666<br />
group = postfix<br />
user = postfix<br />
}<br />
# Create inet listener only if you can't use the above UNIX socket<br />
#inet_listener lmtp {<br />
# Avoid making LMTP visible for the entire internet<br />
#address =<br />
#port =<br />
#}<br />
user=mail<br />
}<br />
<br />
service auth {<br />
# auth_socket_path points to this userdb socket by default. It's typically<br />
# used by dovecot-lda, doveadm, possibly imap process, etc. Its default<br />
# permissions make it readable only by root, but you may need to relax these<br />
# permissions. Users that have access to this socket are able to get a list<br />
# of all usernames and get results of everyone's userdb lookups.<br />
unix_listener /var/spool/postfix/private/auth {<br />
mode = 0666<br />
user = postfix<br />
group = postfix<br />
}<br />
unix_listener auth-userdb {<br />
mode = 0600<br />
user = mail<br />
#group =<br />
}<br />
# Postfix smtp-auth<br />
#unix_listener /var/spool/postfix/private/auth {<br />
# mode = 0666<br />
#}<br />
# Auth process is run as this user.<br />
user = dovecot<br />
}<br />
service auth-worker {<br />
# Auth worker process is run as root by default, so that it can access<br />
# /etc/shadow. If this isn't necessary, the user should be changed to<br />
# $default_internal_user.<br />
user = mail<br />
}<br />
}}<br />
<br />
And last, but not least, {{f|/etc/dovecot/conf.d/10-ssl.conf}}:<br />
<br />
{{file|name=/etc/dovecot/conf.d/10-ssl.conf|desc=Dovecot SSL config|body=<br />
ssl_cert = </etc/ssl/certs/dovecot.pem<br />
ssl_key = </etc/ssl/private/dovecot.pem<br />
ssl = required<br />
}}<br />
<br />
We now need to generate the SSL certificates that Postfix and Dovecot are looking for. When it asks for a FQDN for the certificate, make sure to put in the FQDN of the mail server:<br />
<br />
{{console|body=<br />
###i## openssl req -new -x509 -days 1000 -nodes -out "/etc/ssl/certs/dovecot.pem" -keyout "/etc/ssl/private/dovecot.pem"<br />
}}<br />
<br />
Yes, they are self-signed certificates; if that bothers you feel free to buy one from GoDaddy or some other CA. It won't make things more secure (self-signed certificates have an undeserved bad reputation), but it will make you slightly poorer and the CA slightly richer.<br />
<br />
Finally, we set the permissions on the Dovecot config files so they belong to {{c|mail:dovecot}} and nobody else:<br />
<br />
{{console|body=<br />
###i## chown -R mail:dovecot /etc/dovecot<br />
###i## chmod -R o-rwx /etc/dovecot<br />
}}<br />
<br />
== Final Steps ==<br />
<br />
We want Postfix and Dovecot to come up when our server boots up, so we need to add them to the server's startup; once that's done, we'll start Postfix and Dovecot with the {{c|rc}} command:<br />
<br />
{{console|body=<br />
###i## rc-update add postfix default<br />
###I## rc-update add dovecot default<br />
###i## rc<br />
}}<br />
<br />
== Client Configuration ==<br />
<br />
<br />
<br />
== Success! ==</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17177Mail Server2016-12-14T00:57:35Z<p>Shamus397: I guess not... :-P</p>
<hr />
<div>= How to set up a simple, secure, lightweight email server using Postfix and Dovecot =<br />
<br />
Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
__TOC__<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. Setting up such a thing is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: {{c|mail-mta/postfix}}, {{c|net-mail/dovecot}}, and {{c|dev-db/mariadb}}. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
{{console|body=###i## emerge -avq postfix mariadb}}<br />
<br />
Setting the {{c|dovecot-sasl}} USE flag should pull in {{c|net-mail/dovecot}}. If it does not, emerge this way:<br />
<br />
{{console|body=###i## emerge -avq postfix dovecot mariadb}}<br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running (be sure to replace ''<strong-password>'' with a real, strong password):<br />
<br />
{{console|body=###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc}}<br />
<br />
Next, we need to login to MySQL (you will have to enter the ''<strong-password>'' you set above):<br />
<br />
{{console|body=###i## mysql -p}}<br />
<br />
Now, we create the database and its tables (again, replace ''<mailuserpass>'' with a real password):<br />
<br />
{{console|body=<br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
}}<br />
<br />
Now that we've created our database and tables, we need to put our domain into it. Replace ''<my.fqdn.com>'' with the FQDN of that will go to the right of the '@' sign in email addresses on your mail domain:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_domains VALUES (DEFAULT, '<my.fqdn.com>');}}<br />
<br />
{{note|If you're planning on receiving mail for more than one domain, you can add them by reusing the previous query and changing ''<my.fqdn.com>'' to the other domain(s); you will have to enter one query for each extra domain.}}<br />
<br />
Next, we need to populate that database with users (the part that goes on the left side of the '@' sign). Again, these need to be added one at a time. For each entry in the database, we will need a username and a password; since we want these passwords to be strong, we will use doveadm to generate them:<br />
<br />
{{ console|body=<br />
###i## doveadm pw -s SHA512-CRYPT<br />
Enter new password: <br />
Retype new password: <br />
{SHA512-CRYPT}$6$dMNWSDK.CYzDfADO$LLSqttmYD/3WDBIEwxLjzae1s0G.eQw6EU8U7cjysPDK/z3Pntz8gxabfrYmLzpdc.L3gMyxaoI4V9ci4zruM.<br />
}}<br />
<br />
You will be prompted to enter the password twice before it gives back the hash. The part that comes after {{c|{SHA512-CRYPT}}} is the password that will need to go into the database (it will always start with {{c|$6$}}).<br />
<br />
{{note|The password you will distribute to your users is the one you typed into {{c|doveadm}}; the hash that it outputs is what will go into the {{c|virtual_users}} table.}}<br />
<br />
Replace ''<pw_hash>'' with the output of {{c|doveadm}} (starting with {{c|$6$}}), and ''<user@my.fqdn.com>'' with the email address for the user you're creating:<br />
<br />
{{console|body=mysql>##i## INSERT INTO virtual_users VALUES (DEFAULT, 1, '<pw_hash>', '<user@my.fqdn.com>');}}<br />
<br />
{{note|The second field in the query above (the '1') is the ID of the entry in the {{c|virtual_domains}} table. If you're only using one domain, you don't have to worry about changing it; otherwise, you will have to change it to correspond to the domain for that user. You can find out what IDs they have with the following query:<br />
<br />
{{console|body=mysql>##i## SELECT * FROM virtual_domains;}} }}<br />
<br />
Once you are done entering users you can leave MySQL:<br />
<br />
{{console|body=mysql>##i## quit}}<br />
<br />
<br />
=== Configuring Postfix ===<br />
<br />
=== Configuring Dovecot ===<br />
<br />
== Success! ==</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17176Mail Server2016-12-13T23:00:10Z<p>Shamus397: Does this not get saved with the content? :-P</p>
<hr />
<div>Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. Setting such a thing up is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: <code>mail-mta/postfix</code>, <code>net-mail/dovecot</code>, and <code>dev-db/mariadb</code>. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
<console>###i## emerge -avq postfix mariadb</console><br />
<br />
Setting the <code>dovecot-sasl</code> USE flag should pull in <code>net-mail/dovecot</code>. If it does not, emerge this way:<br />
<br />
<console>###i## emerge -avq postfix dovecot mariadb</console><br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
First step is to set up the database for the virtual domain/user tracking. We need to set up the database's root user and get the database up and running:<br />
<br />
<console>###i## mysqladmin -u root password '<strong-password>'<br />
###i## rc-update add mysql default<br />
###i## rc</console><br />
<br />
Next, we need to login to MySQL (you will have to enter the <strong-password> you set above):<br />
<br />
<console>###i## mysql -p</console><br />
<br />
Now, we create the database and its tables:<br />
<br />
<console><br />
mysql>##i## CREATE DATABASE mailserver;<br />
mysql>##i## USE mailserver;<br />
mysql>##i## GRANT SELECT ON mailserver.* TO 'mailuser'@'127.0.0.1' IDENTIFIED BY '<mailuserpass>';<br />
mysql>##i## FLUSH PRIVILEGES;<br />
mysql>##i## CREATE TABLE virtual_domains (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## name VARCHAR(50) NOT NULL, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_users (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, password VARCHAR(106) NOT NULL, email VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), UNIQUE KEY email (email), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id)<br />
##i## ON DELETE CASCADE) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## CREATE TABLE virtual_aliases (id INT(11) NOT NULL AUTO_INCREMENT,<br />
##i## domain_id INT(11) NOT NULL, source VARCHAR(100) NOT NULL, destination VARCHAR(100) NOT NULL,<br />
##i## PRIMARY KEY (id), FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE)<br />
##i## ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
mysql>##i## INSERT INTO virtual_domains VALUES (1, 'mymail.server.com');<br />
</console><br />
<br />
=== Configuring Postfix ===<br />
<br />
=== Configuring Dovecot ===<br />
<br />
== Success! ==</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17175Mail Server2016-12-13T22:17:01Z<p>Shamus397: </p>
<hr />
<div>Running one's own email server doesn't have to be mystical and impenetrable; using a simple MTA like Postfix along with an LDA like Dovecot makes the task relatively easy. Regrettably, good information on how to do this is hard to come by. What this guide will help you do is install a mail server which uses a database backend to manage domains and users, and features mail delivery via POP3 and/or IMAP.<br />
<br />
== Prerequisites ==<br />
<br />
If you intend to run your own email server, you will need to have DNS with at least one MX record on a DNS server that can be seen by the Internet at large. Setting such a thing up is beyond the scope of this document.<br />
<br />
== Preparation ==<br />
<br />
The following packages need to be installed first, before we can do anything: <code>mail-mta/postfix</code>, <code>net-mail/dovecot</code>, and <code>dev-db/mariadb</code>. Before we emerge these, however, we must ensure some USE flags are properly set first:<br />
<br />
{{file|name=/etc/portage/package.use/mail-server|desc=USE flags|body=mail-mta/postfix dovecot-sasl pam ssl<br />
net-mail/dovecot bzip2 maildir pam ssl zlib}}<br />
<br />
With USE flags properly set, we can emerge our packages:<br />
<br />
<console>###i## emerge -avq postfix mariadb</console><br />
<br />
Setting the <code>dovecot-sasl</code> USE flag should pull in <code>net-mail/dovecot</code>. If it does not, emerge this way:<br />
<br />
<console>###i## emerge -avq postfix dovecot mariadb</console><br />
<br />
== Configuration ==<br />
<br />
Now we come to the meat of the project. First we will have to set up the mail user/domain database, then we will have to configure Postfix, then finally, configure Dovecot. At the end of this procedure, we should have a fully functioning mail server.<br />
<br />
=== Setting up the Database ===<br />
<br />
=== Configuring Postfix ===<br />
<br />
=== Configuring Dovecot ===<br />
<br />
== Success! ==</div>Shamus397https://www.funtoo.org/index.php?title=Mail_Server&diff=17174Mail Server2016-12-13T21:37:51Z<p>Shamus397: How to set up a simple, secure, lightweight email server using Postfix and Dovecot</p>
<hr />
<div>Running one's own email server doesn't have to be mystical and impenetrable, using a simple MTA like Postfix along with an LDA like Dovecot. Regrettably, good information on how to do this is hard to come by.</div>Shamus397https://www.funtoo.org/index.php?title=Nfs&diff=15803Nfs2016-01-26T14:22:27Z<p>Shamus397: /* NFS */</p>
<hr />
<div>= NFS =<br />
<br />
This wiki will explain how to install and use NFS (a Network File System) on Funtoo/Linux. Before we start a little hint for those who already searched for information :<br />
<br />
Recent linux has NO need to do any tuning like suggested in the old days, like there was often mentioned playing with rsize and wsize parameters and such.<br />
If you don't run outdated kernel/userland, which is unlikely since Funtoo/Linux was not there that time, all necessary parameters are dynamically controlled by the<br />
kernel and will exceed the old values by far, hence you may not wonder if "mount" returns values which are 100 times greater than you expected.<br />
<br />
These Days we differ usually between NFS V3 and NFS V4 which has nothing in common but the name. Older variants are weak,error prone, insecure etc.<br />
and are not mentioned any longer.<br />
<br />
If you plan to setup a new NFS Server, i would strongly recommend V4 because it has several advantages over V3.<br />
<br />
== Installation ==<br />
<br />
In general, you need a kernel with NFS enabled modules or built in, those settings can be found in "File systems" -> "Network file systems" using make menuconfig.<br />
<br />
For generic client functionality you need<br />
<br />
{{console|body=<br />
###i## emerge net-fs/libnfs<br />
###i## emerge net-fs/nfs-utils<br />
}}<br />
<br />
This will give you the necessary tools and environment to mount some NFS from a server or start a server on the machine itself.<br />
<br />
NFS V3 can take care about disappearing and re-appearing machines on the network and deal accordingly with locked files and timeouts, to achieve that, you want to<br />
<br />
{{console|body=<br />
###i## rc-update add rpc.statd default<br />
###i## rc<br />
}}<br />
<br />
the first time you installed it, will be automatic on reboot.<br />
This is not neccessary on pure V4 environments but since it can't be auto-detected the rc-script will force it. If you won't use V 3 at all, you may remove it from the scripts dependencies<br />
by editing /etc/init.d/nfs and /etc/init.d/nfsmount and remove "rpc.statd" from need.<br />
<br />
== NFS V3 syntax ==<br />
<br />
If you consider to use only V3, you need to add some exported directories in /etc/exports, this can be something like this :<br />
<br />
{{file|name=/etc/exports|desc=NFS V3 export syntax|body=<br />
...<br />
10.0.0.0/8 /absolute/path/to/desired/dir (rw,async)<br />
some.domain.tld /another/full/path/to/dir2 (ro,async)<br />
...<br />
}}<br />
<br />
and several alternative globbing with additional options where "man exports" gives you a good overview. One of the biggest differences to V4 ( see below ) in dirs export<br />
is the fact you write absolute paths ( from / downwards to the dir ) and V3 cares not about about username but uid.<br />
<br />
{{important|NFS V3 is mapping uids on the exported files and dirs, this can become cumbersome on networks with different uids on the clients}}<br />
<br />
==NFS V4 syntax==<br />
<br />
If you consider to use V4, you need to add exported directories in a different way, there is only one NFSROOT and all other dirs have to appear below that :<br />
<br />
{{file|name=/etc/exports|desc=NFS V4 export syntax|body=<br />
...<br />
10.0.0.0/8 /srv (fsid=0,rw,async,no_root_squash,no_all_squash)<br />
some.domain.tld /srv/dir2 (ro,async)<br />
...<br />
}}<br />
<br />
In this situation, we define the root of your nfs to be /srv ( latest V4 will take the first entry, early V4 used the above fsid=0 to mark it. This is considered deprecated but doesn't harm ).<br />
Also, we define another dir below NFSROOT, here /srv/dir2 which is meant to be mounted relative. ( See below ). You may mount a dir that exists somewhere else but in that case you<br />
need to bind-mount it for V4. e.g. if you want to export /mnt/another, you get this done by<br />
<br />
{{console|body=<br />
###i## mkdir /srv/dir2<br />
###i## mount -o bind /mnt/another /srv/dir2<br />
}}<br />
<br />
If you do so, remember to add the mount also in fstab for next reboot :<br />
{{console|body=<br />
##y##/srv/dir2 /mnt/another bind defaults 0 0<br />
}}<br />
<br />
== Activate changes on servers ==<br />
<br />
Whenever you add or change settings in /etc/exports, there is no need to restart the server(s), else just<br />
<br />
{{console|body=<br />
###i##exportfs -rv<br />
}}<br />
<br />
== ID mapping ==<br />
<br />
Like mentioned above, V4 does not care any longer for uids but will use username@machine instead. This is a big improvement since we must not longer care about the order of given users when adding accounts. However, if for some reason the protocol version 4 becomes inappropriate ( old client, bad parameters etc.) it will automatically fall back to use V3 where we need a way to get the different behavior somehow mapped, this is also the case in mixed environments and such where we have a solution for this. If you plan to use V4, you want to :<br />
<br />
{{console|body=<br />
###i## emerge net-libs/libnfsidmap<br />
###i## rc-update add rpc.idmapd default<br />
###i## rc<br />
}}<br />
<br />
which will care about such situations.<br />
<br />
== Mounting V3 export from clients ==<br />
<br />
Using V3, you have to specify the server and it's absolute path to the exported dir, this can be by IP like this :<br />
<br />
{{console|body=<br />
###i##mount -t nfs 10.0.8.254:/my/absolute/path/to/mounting/location /somewhere<br />
}}<br />
<br />
Or you may use a hostname or FQDN but only if you have a proper setup to resolve that reproducible from the client ( e.g. entry in /etc/hosts or local DNS servers etc. ) :<br />
<br />
{{console|body=<br />
###i## mount -t nfs nfsserver:/my/absolute/path/to/mounting/location /somewhere<br />
}}<br />
<br />
Mounted via fstab, this would look like :<br />
{{console|body=<br />
##y##/somewhere 10.0.8.254:/my/absolute/path/to/mounting/location nfs defaults 0 0<br />
##y##/somewhere nfsserver:/my/absolute/path/to/mounting/location nfs defaults 0 0<br />
}}<br />
<br />
the usage of IPs is recommented for machines mounting their own root on NFS to avoid early resolving issues.<br />
<br />
== Mounting V4 export from clients ==<br />
<br />
Using V4, you DONT specify the absolute path, else it will fall back to V3 :<br />
<br />
{{console|body=<br />
###i## mount -t nfs4 10.0.8.254:/dir2 /somewhere<br />
}}<br />
<br />
( Above example exported by /srv/dir2 aka $NFSROOT/dir2 )<br />
You may also use a hostname or FQDN <br />
<br />
and in fstab :<br />
<br />
{{console|body=<br />
##y##/somewhere 10.0.8.254:/dir2 nfs4 defaults 0 0<br />
##y##/somewhere nfsserver:/dir2 nfs4 defaults 0 0<br />
}}<br />
<br />
== Hints ==<br />
<br />
The use of -t nfs resp -t nfs4 is most likely redundant, recent userland has a good auto-detection.<br />
If not specially mentioned, nfs will map your users to nobody:nogroup, if you want to differ them on exported dirs, use the above mentioned "no_all_squash" option,<br />
The local user root is not necessarily the same superuser like on the server, if you want him to be the same, use "no_root_squash" else he is nobody ;)<br />
<br />
== Troubleshooting ==<br />
<br />
As was noted above, with the latest versions of NFS problems should be rare. But when they crop up, they can be a bear. So collected here are some of those things that can bite you and make you pull out your hair.<br />
<br />
Problem: NFS seems to work for the most part, but from time to time will hang with threads stuck in a 'D' state.<br />
<br />
Solution: Check to see if there is an IP collision on your network. If there is, then resolve the collision and NFS should not hang anymore.</div>Shamus397https://www.funtoo.org/index.php?title=Raspberry_Pi_2&diff=15493Raspberry Pi 22015-11-04T17:19:53Z<p>Shamus397: Exchange chrony for ntp, since chrony is lighter/easier to use</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_neonvfpv4_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Armv7a_neonvfpv4_hardfp). Also add the option to utilise all four cores while compiling:<br />
<br />
{{file|name=~/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfpu=neon-vfpv4 -mfloat-abi=hard"<br />
MAKEOPTS="-j4"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## rc-update add dhcpcd default<br />
###i## rc<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system (the emerge --sync is optional):<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your RPi2 for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge -av chrony<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc:<br />
{{console|body=<br />
###i## rc-update add chronyd default<br />
###i## rc<br />
###i## rc-update add swclock boot<br />
}}<br />
<br />
Since the RPi2 doesn't have a hardware clock, remove the hwclock startup script from bootup:<br />
{{console|body=<br />
###i## rc-update del hwclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Installing_Funtoo_on_a_Raspberry_Pi_2&diff=15434Installing Funtoo on a Raspberry Pi 22015-11-01T02:29:41Z<p>Shamus397: Redirecting to better named page</p>
<hr />
<div>#REDIRECT [[Raspberry Pi 2]]</div>Shamus397https://www.funtoo.org/index.php?title=Raspberry_Pi_2&diff=15433Raspberry Pi 22015-11-01T02:26:57Z<p>Shamus397: Keeping things consistent with the rest of the RPi pages.</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Arm7va_hardfp). Also add the option to utilize all four cores while compiling:<br />
<br />
{{file|name=/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfloat-abi=hard"<br />
MAKEOPTS="-j4"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## rc-update add dhcpcd default<br />
###i## rc<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system (the emerge --sync is optional):<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your RPi2 for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge ntp -av<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc:<br />
{{console|body=<br />
###i## rc-update add ntp-client default<br />
###i## rc<br />
###i## rc-update add swclock boot<br />
}}<br />
<br />
Since the RPi2 doesn't have a hardware clock, remove the hwclock startup script from bootup:<br />
{{console|body=<br />
###i## rc-update del hwclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Funtoo_Linux_Installation_on_ARM&diff=15432Funtoo Linux Installation on ARM2015-11-01T01:16:50Z<p>Shamus397: Added RPi2 :-)</p>
<hr />
<div>Funtoo now provides [http://ftp.osuosl.org/pub/funtoo/funtoo-current/arm-32bit/ stage3 images] for arm platform. At this time armv5te, armv6j_hardfp and armv7a_hardfp stages available. If you would like us to support other processors (see the list below), please fill a bug report on [http://bugs.funtoo.org].<br />
<br />
<br />
== List of ARM processor "flavors" ==<br />
* armv4l-unknown-linux-gnu (Rebel NetWinder, HP Armada and other devices having an ARMv4 processor, which is only capable of running the old ABI. Nevertheless it should work on newer CPUs)<br />
* armv4tl-softfloat-linux-gnueabi (OpenMoko FreeRunner and other devices using an ARMv4T processor. Uses the new ARM EABI and software floating point by default)<br />
* armv5tel-softfloat-linux-gnueabi (almost all ARM NAS, devices based on the Marvell Orion and Marvell Kirkwood, Marvell Sheevaplug, Marvell OpenRD, Guruplug, Dreamplug, QNAP TS109/TS209/TS409/TS119/TS219/TS419, Buffalo Linkstation/Kurobox PRO, HP mv2120, HP iPAQ, Linksys NSLU2 and other devices using an ARMv5TE processor. Uses the new ARM EABI and software floating point by default)<br />
* armv6j-unknown-linux-gnueabi ([[Raspberry Pi]], Nokia N800/N810, Smart Q7, OMAP2-based devices and other multimedia devices using an ARMv6 CPU and VFP. Uses the new ARM EABI and hardware floating point by default)<br />
* armv7a-unknown-linux-gnueabi (OMAP3-based devices(Beagleboard, IGEPv2, Devkit8000, AlwaysInnovating Touchbook, [[Nokia N900]]), OMAP4-based devices([[Pandaboard]]), Freescale i.MX515-based devices([[Efika MX]], Babbage Board, Lange Board…) Marvell Dove/Armada, Nvidia Tegra2-based devices(Toshiba AC100, Toshiba Folio), ST-Ericsson NOVA A9500-based devices(Snowball), Exynos 4412 ([[Odroid-X]], Odroid-Q, [[ODROID U2]]) and other devices using an ARMv7-A processor. Uses the new ARM EABI and generic(not NEON) hardware floating point by default<br />
* armv7a-hardfloat-linux-gnueabi ([[Raspberry Pi 2]]. The same as armv7a-unknown-linux-gnueabi, but this one uses hardfloat instead of softfp. Read more about it here: http://wiki.debian.org/ArmHardFloatPort)<br />
<br />
== Default installation of Funtoo on your platform/board ==<br />
This document is not a complete installation tutorial. Basic information about Funtoo Linux installation can be found on [[Funtoo Linux Installation]]. The goal of this document is to provide general information about installing Funtoo Linux on an ARM device, and highlight differences with a x86 installation.<br />
<br />
The following notes are non-board specific. Other instructions can be found in the specific articles for the above mentioned devices.<br />
<br />
=== Overview ===<br />
Most of the ARM boards come with a SD card slot, so you will need an empty SD card (4GB is enough to get you started), in most cases the boards are also equipped with debug port which can be used with USB-to-serial cables, if you have one, you can use it to login to the machine without the need of connecting keyboards or displays. You will need a network connection to be able to download stages, kernel and update your portage tree.<br />
<br />
=== Kernel and bootloader setup ===<br />
Before you start you will need a kernel and a bootloader for your device. Some of the devices look for bootloader (in most cases U-Boot) on the SD along with the kernel.<br />
<br />
More information about the kernel and bootloader can be found on pages specific for your device.<br />
<br />
=== Installing Funtoo (overview) ===<br />
<br />
The installation on these devices differs from the normal installation procedure of booting an installation environment and chrooting from there to your new root, and can be little bit easier, but in some cases tricky. <br />
<br />
Overview of the installation:<br />
* Extract stage3 to the 2nd partition of the SD card<br />
* Extract portage snapshot<br />
* Setup fstab<br />
* Setup root password<br />
* Configure hostname and networking (optional, but recommended)<br />
* Enable SSH access (optional, but recommended)<br />
* Enable serial console access (optional, but recommended)<br />
* Correct RTC "bug" with swclock<br />
<br />
==== Installing the Stage 3 tarball ====<br />
<br />
ARM stage3 tarballs can be found on [http://ftp.osuosl.org/pub/funtoo/funtoo-current/arm-32bit/]. Use the subarchitecture that suits best your device.<br />
<br />
Mount the partition that will hold your rootfs of the SD card and extract the stage3 you have downloaded.<br />
<br />
<console><br />
# ##i##mkdir /mnt/SD_root<br />
# ##i##mount /dev/sdcard-device-px /mnt/SD_root<br />
</console><br />
<br />
Extract the stage3 (it may take a while).<br />
<console><br />
# ##i##tar xapf stage3-armv7a_hardfp-xxxx.tar.xz -C /mnt/SD_root<br />
</console><br />
<br />
==== Extracting a portage snapshot ====<br />
<br />
Now, download the portage snapshot from [http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/], and extract it to your partition.<br />
<br />
<console><br />
# ##i##tar xapf portage-latest.tar.xz -C /mnt/SD_root/usr<br />
</console><br />
<br />
==== Setup fstab ====<br />
Edit the <tt>/mnt/SD_root/etc/fstab</tt> file to look like this:<br />
<br />
<pre><br />
/dev/mmcblk0p1 /boot vfat noauto,noatime 1 2<br />
/dev/mmcblk0p2 / ext4 noatime 0 1<br />
</pre><br />
<br />
Adjust the partition devices and types to suit your needs.<br />
<br />
==== Setting the default root password ====<br />
<br />
{{fancywarning|Don't skip this step. This part differs from the standard installation procedure, as the root password must be set outside of a chroot environment. Skipping this step will result in an impossibility to login.}}<br />
<br />
Normally, for setting the password, one has to be able to run passwd. However that's not possible in this case since an x86 system can't run ARM binaries. Therefore, it is needed to modify the file that contains the passwords (<tt>/etc/shadow</tt>) to set a default root password.<br />
<br />
===== Clearing the root password =====<br />
This will allow to login with a blank password for the root user.<br />
<console><br />
# ##i##nano -w /mnt/SD_root/etc/shadow<br />
</console><br />
<br />
Modify the line beginning by "root" to match the following:<br />
<br />
<pre><br />
root::10770:0:::::<br />
</pre><br />
<br />
{{fancywarning|After initial login, remember to change the root password using the passwd command.}}<br />
This didn't work for me. I hit enter at the password prompt, it gave me 3 tries, that was it. I solved the problem by adding my public key to /root/.ssh/authorized_keys (had to be created). Then I was accepted by public key authentication.<br />
<br />
===== Choosing a root password (alternative) =====<br />
<br />
First, generate a password. The output of this command will be used to modify the shadow file.<br />
<console><br />
# ##i##openssl passwd -1<br />
or<br />
# ##i##python -c "import crypt, getpass, pwd; print crypt.crypt('password', '\$6\$SALTsalt\$')"<br />
</console><br />
<br />
Then, edit the shadow file and use the output of the last command to replace "YOUR_PASSWORD_MD5".<br />
<br />
<console><br />
# ##i##nano -w /mnt/SD_root/etc/shadow<br />
</console><br />
<br />
<pre><br />
root:YOUR_PASSWORD_MD5:14698:0:::::<br />
</pre><br />
<br />
==== Setup hostname and networking ====<br />
<br />
Please read the [[Funtoo Linux Networking]] to configure your network.<br />
<br />
<br />
==== Using swclock ====<br />
One of the problems some of the devices have, is that they don't have a battery to save the clock time. To mitigate this, on Funtoo we have an option in our init system called swclock which sets the date of the system upon boot from a last modified date of a file.<br />
<br />
<br />
First, add swclock to the boot runlevel.<br />
<console><br />
# ##i##ln -sf /etc/init.d/swclock /mnt/SD_root/etc/runlevels/boot<br />
</console><br />
<br />
Then, remove hwclock from the startup because it sets the date from the RTC, which is 2000-01-01 upon startup and overrides swclock's date.<br />
<console><br />
# ##i##rm /mnt/SD_root/etc/runlevels/boot/hwclock<br />
</console><br />
<br />
swclock uses the <tt>/lib/rc/cache/shutdowntime</tt> modification time to set the date, therefore we update it to have the current date and time.<br />
<console><br />
# ##i##touch /mnt/SD_root/lib/rc/cache/shutdowntime<br />
</console><br />
<br />
Although this doesn't fix the issue, at least helps to set a sane date and time.<br />
Note: Consider using NTP, documented on the next chapter<br />
<br />
<br />
==== Enabling SSH access (optional) ====<br />
Adding sshd to the default runlevel will enable access to the device using ssh (if network has been configured).<br />
<br />
<console><br />
# ##i##ln -sf /etc/init.d/sshd /mnt/SD_root/etc/runlevels/default<br />
</console><br />
<br />
If no network has been configured yet, it might be a good idea to add dhcpcd in the default runlevel as well.<br />
<br />
<console><br />
# ##i##ln -sf /etc/init.d/dhcpcd /mnt/SD_root/etc/runlevels/default<br />
</console><br />
<br />
==== Enabling serial console access (optional) ====<br />
By default the ttyS0 port is configured at 9600 bps. However, almost all of the ARM devices run the serial port at 115200 bps. Also, the port device names differ (ttyO2 for Pandaboard, ttySAC1 for Odroid-X ...). So edit your /etc/inittab file:<br />
<br />
<console><br />
# ##i##nano -w /mnt/SD_root/etc/inittab<br />
</console><br />
<br />
Example for Pandaboard:<br />
<pre><br />
s0:12345:respawn:/sbin/agetty 115200 ttyO2 vt100<br />
</pre><br />
<br />
=== Finishing the installation and booting up the new system ===<br />
Let's unmount the SD card.<br />
<console><br />
# ##i##umount /mnt/SD_root<br />
</console><br />
<br />
=== Troubleshooting ===<br />
With the armv5te at least, these instructions work great. However, when it is time to update sys-devel/gcc this underpowered wimp has trouble, mainly due to limited memory I think. Cross-compiling toolchains made by crossdev work well within limits, it won't do gcc. However I have found a trick that works well and solves this, thanks to the timely posting of new stage3's by Funtoo.<br /><br />
Simply make a chroot using qemu-user files as described here: http://wiki.gentoo.org/wiki/Cross_Container_Support_Project<br />
Enter the chroot and tweak your /etc/portage/make.conf to point to the directory you wish to save packages to (PACKAGEDIR) and any other necessary tweaks in there.<br /><br />
Since this latest stage3 will have the latest gcc installed in it, simply enter:<br />
<console><br />
# ##i##quickpkg sys-devel/gcc<br />
</console><br />
It will build the binary package, which then installs on my Dockstar quickly & easily in comparison to compiling 48 hours and then failing.<br /><br />
As an added bonus you now have a nifty arm chroot you may find handy for other tasks.<br />
<br />
<br />
[[Category:HOWTO]]<br />
[[Category:ARM]]</div>Shamus397https://www.funtoo.org/index.php?title=Installing_Funtoo_on_a_Raspberry_Pi_2&diff=15388Installing Funtoo on a Raspberry Pi 22015-10-30T19:37:31Z<p>Shamus397: Added missing things in the booted RPi environment</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Arm7va_hardfp). Also add the option to utilize all four cores while compiling:<br />
<br />
{{file|name=/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfloat-abi=hard"<br />
MAKEOPTS="-j4"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## rc-update add dhcpcd default<br />
###i## rc<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system (the emerge --sync is optional):<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your RPi2 for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge ntp -av<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc:<br />
{{console|body=<br />
###i## rc-update add ntp-client default<br />
###i## rc<br />
###i## rc-update add swclock boot<br />
}}<br />
<br />
Since the RPi2 doesn't have a hardware clock, remove the hwclock startup script from bootup:<br />
{{console|body=<br />
###i## rc-update del hwclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Installing_Funtoo_on_a_Raspberry_Pi_2&diff=15330Installing Funtoo on a Raspberry Pi 22015-10-29T03:15:14Z<p>Shamus397: Fixed wrong stuff at last steps for ntp.</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Arm7va_hardfp). Also add the option to utilize all four cores while compiling:<br />
<br />
{{file|name=/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfloat-abi=hard"<br />
MAKEOPTS="-j4"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## rc-update add dhcpcd default<br />
###i## rc<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system (the emerge --sync is optional):<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your RPi2 for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge ntp -av<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc:<br />
{{console|body=<br />
###i## rc-update add ntp-client default<br />
###i## rc<br />
###i## rc-update add swclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Installing_Funtoo_on_a_Raspberry_Pi_2&diff=15329Installing Funtoo on a Raspberry Pi 22015-10-29T03:10:33Z<p>Shamus397: Added missing things in the booted RPi environment</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Arm7va_hardfp). Also add the option to utilize all four cores while compiling:<br />
<br />
{{file|name=/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfloat-abi=hard"<br />
MAKEOPTS="-j4"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## rc-update add dhcpcd default<br />
###i## rc<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system (the emerge --sync is optional):<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your RPi2 for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge ntp -av<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc-service:<br />
{{console|body=<br />
###i## rc-update add ntp-client default<br />
###i## rc-service ntp-client start<br />
###i## rc-service add swclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Installing_Funtoo_on_a_Raspberry_Pi_2&diff=15328Installing Funtoo on a Raspberry Pi 22015-10-28T22:30:30Z<p>Shamus397: Grammar/spelling, added section on sparse checkout of firmware/boot.</p>
<hr />
<div>This guide draws heavily on [https://plus.google.com/+WolfgangApolinarski/posts/dNTqe6sVW87 Wolfgang Apolinarski's post], [https://wiki.gentoo.org/wiki/Raspberry_Pi Gentoo's Wiki for Raspberry Pi] and the [http://www.funtoo.org/Raspberry_Pi Funtoo Raspberry Pi guide].<br />
<br />
The guides above are quite probably enough to get most people up and running. I had a few issues along the way, so decided to note them down in case they are of use to others.<br />
<br />
== What you need ==<br />
<br />
# Raspberry PI 2<br />
# An existing Linux install to perform pre-install steps on<br />
# A [https://www.raspberrypi.org/help/faqs/#sdCards suitable SD card] for your PI. I used a 16GB class 6 card.<br />
# An HDMI cable<br />
# A USB keyboard<br />
# A cat 5 network cable to connect the PI to your router<br />
<br />
==Prepare your SD card==<br />
===Formatting===<br />
<br />
Insert your SD card into your Linux system. To find out which device it is, issue the following command:<br />
{{console|body=<br />
###i## dmesg tail<br />
}}<br />
<br />
You should see some output identify the device. In my case is was /dev/sdf. In your case, it's quite possibly something different (maybe something like /dev/mmcblk0, e.g.), so please take care to identify the correct device. <br />
<br />
{{warning|Some of the commands coming up WILL DESTROY DATA on existing devices if you pick the wrong one. Most people reading this guide should be familiar with that, but I know I've certainly found guides on the internet in the past and blindly followed along without a full understanding of what is going on...this warning is for that guy!}}<br />
<br />
Now we need to format the SD card to suit our purposes. The following example uses fdisk. If you're more comfortable with a different utility for formatting your drives/cards, you can use that instead.<br />
<br />
First, we run fdisk against our SD card to create boot, root and swap partitions. I gave boot 50MB, swap 256MB and root the rest of the card. I've noticed that the swap space doesn't appear to get used during the time I've spent watching it...perhaps this is un-needed - or perhaps someone who understands how the Pi works a little better can explain it or recommend something better.<br />
<br />
{{console|body=<br />
###i## fdisk /dev/sdf<br />
Welcome to fdisk (util-linux 2.25.2). Changes will remain in memory only, until you decide to write them. <br />
Be careful before using the write command.<br />
<br />
Command (m for help): o <br />
Created a new DOS disklabel with disk identifier 0x7bc6906d.<br />
<br />
Command (m for help): n <br />
Partition type<br />
p primary (0 primary, 0 extended, 4 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (1-4, default 1): <br />
First sector (2048-31326207, default 2048): <br />
Last sector, +sectors or +size{K,M,G,T,P} (2048-31326207, default 31326207): +50M<br />
<br />
Created a new partition 1 of type 'Linux' and of size 50 MiB.<br />
<br />
Command (m for help): t <br />
Selected partition 1 <br />
Hex code (type L to list all codes): c <br />
If you have created or modified any DOS 6.x partitions, please see the fdisk documentation for additional information. <br />
Changed type of partition 'Linux' to 'W95 FAT32 (LBA)'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (1 primary, 0 extended, 3 free) <br />
e extended (container for logical partitions)<br />
Select (default p): p <br />
Partition number (2-4, default 2): <br />
First sector (104448-31326207, default 104448): <br />
Last sector, +sectors or +size{K,M,G,T,P} (104448-31326207, default 31326207): +256M<br />
<br />
Created a new partition 2 of type 'Linux' and of size 256 MiB.<br />
<br />
Command (m for help): t <br />
Partition number (1,2, default 2): 2 <br />
Hex code (type L to list all codes): 82<br />
<br />
Changed type of partition 'Linux' to 'Linux swap / Solaris'.<br />
<br />
Command (m for help): n <br />
Partition type <br />
p primary (2 primary, 0 extended, 2 free) <br />
e extended (container for logical partitions) <br />
Select (default p):<br />
<br />
Using default response p. <br />
Partition number (3,4, default 3): <br />
First sector (628736-31326207, default 628736): <br />
Last sector, +sectors or +size{K,M,G,T,P} (628736-31326207, default 31326207):<br />
<br />
Created a new partition 3 of type 'Linux' and of size 14.7 GiB.<br />
<br />
Command (m for help): w<br />
}}<br />
<br />
===Create File Systems===<br />
Next, we need to create file systems on the partitions:<br />
<br />
{{console|body=<br />
###i## mkfs.vfat -F 16 /dev/sdf1<br />
###i## mkswap /dev/sdf2<br />
###i## mkfs.ext4 /dev/sdf3<br />
}}<br />
<br />
===Download the Necessary Files===<br />
The next step is to get the kernel and boot firmware for the Raspberry Pi 2 from Github.<br />
<br />
<br />
Clone the raspberrypi/firmware repository to the system you are using for setting up. It was about 3.5GB when I did it, so depending on your connection speed, it can take quite a while. You only actually need the contents of the boot folder from the repo, so you can save some time just getting that (see below).<br />
<br />
{{console|body=<br />
###i## mkdir ~/tmp_raspberrypi <br />
###i## cd tmp_raspberrypi <br />
###i## git clone https://github.com/raspberrypi/firmware.git<br />
}}<br />
<br />
<br />
If you aren't on a fast internet connection and/or don't have approximately 3.5GB to burn on your hard drive, then you can do a sparse checkout of the boot subdirectory like so (took only around 75MB):<br />
<br />
{{console|body=<br />
###i## git init firmware<br />
###i## cd firmware/<br />
###i## git remote add origin https://github.com/raspberrypi/firmware.git<br />
###i## git config core.sparsecheckout true<br />
###i## echo "boot/*" >> .git/info/sparse-checkout<br />
###i## git pull --depth=1 origin master<br />
}}<br />
<br />
<br />
Grab the stage 3 files and latest portage snapshot:<br />
<br />
{{console|body=<br />
###i## wget http://build.funtoo.org/funtoo-current/arm-32bit/armv7a_hardfp/stage3-latest.tar.xz<br />
###i## wget http://ftp.osuosl.org/pub/funtoo/funtoo-current/snapshots/portage-latest.tar.xz<br />
}}<br />
<br />
===Prepare Your Boot Partition===<br />
Make mount points for your boot and root partitions on the SD card:<br />
{{console|body=<br />
###i## mkdir ~/piboot ~/piroot<br />
}}<br />
{{note|While I've chosen to call my mount points piboot and piroot and locate them in root's home directory on my system, you can call them whatever you like. As always, take care to modify any commands that follow to suit your environment and choices}}<br />
Mount your SD card:<br />
{{console|body=<br />
###i## mount /dev/sdf1 ~/piboot <br />
###i## mount /dev/sdf3 ~/piroot<br />
}}<br />
<br />
Copy the boot directory from the git repo onto the boot partition of your SD card:<br />
<br />
{{console|body=<br />
###i## cp -r ~/tmp_raspberrypi/firmware/boot/* ~/piboot<br />
}}<br />
<br />
Create a file called cmdline.txt on the boot partition so the rpi can boot into Funtoo:<br />
<br />
Paste this into the file:<br />
{{file|name=cmdline.txt|body=<br />
root=/dev/mmcblk0p3 rw rootwait console=ttyAMA0,115200 console=tty1 selinux=0 plymouth.enable=0 smsc95xx.turbo_mode=N dwc_otg.lpm_enable=0 kgdboc=ttyAMA0,115200 elevator=noop<br />
}}<br />
<br />
===Get the Funtoo Files Onto the SD Card===<br />
Next you need to get the Funtoo files onto the root partion of the rpi.<br />
<br />
Extract the stage 3 files to your rpi root partition:<br />
{{console|body=<br />
###i## tar xf stage3-latest.tar.xz -C ~/piroot<br />
}}<br />
Now it's time to unpack the portage tree into the /usr directory of piroot:<br />
{{console|body=<br />
###i## tar xf portage-latest.tar.xz -C ~/piroot/usr<br />
}}<br />
===Pre-boot Configuration===<br />
Edit your make.conf file to optimise it for the Raspberry PI (taken from http://www.funtoo.org/Arm7va_hardfp)<br />
<br />
{{file|name=/piroot/etc/portage/make.conf|desk make.conf file|body=<br />
CHOST="armv7a-hardfloat-linux-gnueabi"<br />
CFLAGS="-O2 -pipe -march=armv7-a -mfloat-abi=hard"<br />
}}<br />
<br />
Edit your fstab file so everything mounts correctly on boot:<br />
{{console|body=<br />
###i## vim ~/piroot/etc/fstab<br />
}}<br />
{{file|name=~/piroot/etc/fstab|body=<br />
/dev/mmcblk0p1 /boot vfat defaults 0 2<br />
/dev/mmcblk0p2 none swap sw 0 0 <br />
/dev/mmcblk0p3 / ext4 defaults 0 1<br />
}}<br />
<br />
Set a password for root on your Rapsberry Pi by generating the password hash and modifying the shadow file on the SD card.<br />
<br />
Generate the password hash:<br />
{{console|body=<br />
###i## openssl passwd -1 <br />
}}<br />
<br />
Copy the output hash (e.g.: 1z/p4HaT6$QrIaz/RTpBEIorIkzW4Ac.) and paste it into ~/piroot/etc/shadow<br />
Remove the asterisk (*) after "root" and replace it with the hash output.<br />
<br />
In ~/piroot/etc/inittab search for s0 and disable the line by commeting it out<br />
{{file|name=~/piroot/etc/inittab|body=<br />
---snip---<br />
#s0:12345:respawn:/sbin/agetty -L 9600 ttyS0 vt100<br />
---snip---<br />
}}<br />
<br />
Make sure all buffers have been flushed and unmount the temp directories:<br />
{{console|body=<br />
###i## sync <br />
###i## umount ~/piboot ~/piroot<br />
}}<br />
<br />
{{tip|You could remove the directories and files you've used during the install if you want, but it's probably a good idea to leave them there just in case something isn't working right and you need to come back and check/reconfigure things on the SD card.}}<br />
<br />
==Booting the Raspberry Pi 2==<br />
Now for the fun part!<br />
<br />
Insert the SD card into Rpi. Connect your keyboard, monitor and network card, then power it on. It should boot into Funtoo very quickly. If it doesn't work, go back through the guide and make sure you've got everything configured correctly - in particular the cmdline.txt file on the boot partition.<br />
<br />
Log in using the password you created earlier. The first thing you'll want to do is fix the clock, set your time zone and sync your portage tree.<br />
<br />
Because the Raspberry Pi does not have a hardware clock, you'll need to set the date and time right away. Later on we'll make sure we can get the correct time at boot via NTP, but for now we need to do it manually<br />
{{console|body=<br />
###i## date MMDDHHMMCCYY<br />
}}<br />
<br />
Next, set your timezone:<br />
{{console|body=<br />
###i## ln -sf /usr/share/zoneinfo/YOURTIMEZONE /etc/localtime<br />
}}<br />
<br />
Now we need make sure we can connect to the internet:<br />
{{console|body=<br />
###i## /etc/init.d/dhcpcd start<br />
}}<br />
<br />
The next step is to initialise our portage tree so we can start installing additional packages to our system:<br />
{{console|body=<br />
###i## cd /usr/portage <br />
###i## git checkout funtoo.org<br />
###i## emerge --sync<br />
}}<br />
Set your profile with epro:<br />
<br />
Depending on what you'll be using your rpi for, use epro to set your profile:<br />
{{console|body=<br />
###i## epro subarch armv7a_hardfp <br />
###i## epro flavor server<br />
}}<br />
<br />
Now is a good time to enable swclock NTP so we can be sure to set the correct time the next time we boot:<br />
{{console|body=<br />
###i## emerge ntp -av<br />
}}<br />
Once this finishes building, use rc-update to add it to the default run-level, and start the service with rc-service:<br />
{{console|body=<br />
###i## rc-update add ntp-client default<br />
###i## rc-service ntp-client start<br />
###i## rc-service add swclock boot<br />
}}<br />
<br />
Now you can follow the [[Funtoo Linux Installation|Funtoo Install documentation]] to continue configuring your system. You'll definitely want to look into {{Package|sys-devel/distcc}} if you are going to be adding lots of software to your system.</div>Shamus397https://www.funtoo.org/index.php?title=Install/Kernel&diff=8882Install/Kernel2015-01-31T16:53:19Z<p>Shamus397: /* Building the Kernel */</p>
<hr />
<div><noinclude><br />
{{InstallPart|Kernel Installation}}<br />
</noinclude><br />
=== Configuring and installing the Linux kernel ===<br />
<br />
Now it's time to build and install a Linux kernel, which is the heart of any Funtoo Linux system. The kernel is loaded by the boot loader, and interfaces directly with your system's hardware, and allows regular (userspace) programs to run.<br />
<br />
A kernel must be configured properly for your system's hardware, so that it supports your hard drives, file systems, network cards, and so on. More experienced Linux users can choose to install kernel sources and configure and install their own kernel. If you don't know how to do this, we provide ebuilds that will automatically build a "univeral" kernel, modules and initramfs for booting your system that supports all hardware. This is an extremely simple way of building a kernel that will get your system booted.<br />
<br />
What is our goal? To build a kernel that will recognize all the hardware in your system necessary for booting, so that you will be greeted by a friendly login prompt after installation is complete. These instructions will guide you through the process of installing a kernel the "easy" way -- without requiring user configuration, by using a "universal" kernel.<br />
<br />
==== Package Sets ====<br />
<br />
Before we install a kernel, we're going to cover a feature of Portage called package sets. Portage, the package manager/ports system for Funtoo Linux, will keep track of system packages as well as packages you have installed by calling <code>emerge</code> directly. These packages that are part of the base system are considered part of the "system" package set, while packages that you have installed by typing them on the command line (such as "gnome" in <code>emerge gnome</code>) will be added to the "world" package set. This provides an easy way to update your entire system.<br />
<br />
However, sometimes it's nice to be able to update the kernel all by itself, or leave a kernel update out of your regular whole system update. To do this, we will create a new package set called "kernel".<br />
<br />
==== Kernel Package Set ====<br />
<br />
To create the kernel package set, perform the following steps:<br />
<br />
<console><br />
(chroot) # ##i##mkdir /etc/portage/sets<br />
(chroot) # ##i##echo sys-kernel/debian-sources > /etc/portage/sets/kernel<br />
</console><br />
<br />
Now, we'll want to set a USE variable to tell <code>debian-sources</code> to build a "universal" kernel and initramfs for us, to take the guess-work out of getting Funtoo Linux booted. To do this, we're going to set the <code>binary</code> USE variable for <code>debian-sources</code>, as follows:<br />
<br />
<console><br />
(chroot) # ##i##echo "sys-kernel/debian-sources binary" >> /etc/portage/package.use<br />
</console><br />
<br />
If USE variables are new to you, you'll be getting a lot more familiar with them as you use Funtoo Linux. At their essence, they are "switches" that you can set to configure options that can be built in to various packages. They're used to customize your Funtoo Linux system to meet your exact needs. We added support for a <code>binary</code> USE flag to the <code>debian-sources</code> ebuilds, as well as a few other of our kernel ebuilds, to make it easier for new users to get Funtoo Linux up and running.<br />
<br />
Now, when we just want to update our system's packages, we'll type <code>emerge -auDN @world</code>, and it will update our world set, leaving out the kernel. Likewise, when we just want to update our kernel, we'll type <code>emerge -au @kernel</code>, and it will update our kernel, leaving out the world set.<br />
<br />
==== Building the Kernel ====<br />
<br />
{{Fancynote|1=<br />
See [[Funtoo Linux Kernels]] for a full list of kernels supported in Funtoo Linux. We recommend <code>debian-sources</code> for new users.}}<br />
<br />
{{fancyimportant|1=<br />
<code>debian-sources</code> with <code>binary</code> USE flag requires at least 14GB free in <code>/var/tmp</code> and takes around 1 hour to build on a Intel Core i7 Processor.}}<br />
<br />
Let's emerge our kernel:<br />
<br />
<console><br />
(chroot) # ##i##emerge -1 @kernel<br />
</console><br />
<br />
{{Important|Right now, the <code>-1</code> option is required to not add our <code>@kernel</code> set to <code>world-sets</code>. This allows you to emerge it independently from @world. If you forget to use this option, edit <code>/var/lib/portage/world-sets</code> and remove the <code>@kernel</code> line. This will prevent kernel updates from being included in @world updates.}}<br />
<br />
Note that while use of the <code>binary</code> USE flag makes installing a working kernel extremely simple, it is one part of Funtoo Linux that takes a ''very'' long time to build from source, because it is building a kernel that supports ''all'' hardware that Linux supports! So, get the build started, and then let your machine compile. Slower machines can take up to several hours to build the kernel, and you'll want to make sure that you've set <code>MAKEOPTS</code> in <code>/etc/portage/make.conf</code> to the number of processing cores/threads (plus one) in your system before starting to build it as quickly as possible -- see the [[#/etc/portage/make.conf|/etc/portage/make.conf section]] if you forgot to do this.<br />
<br />
{{fancynote|NVIDIA card users: the <code>binary</code> USE flag installs the Nouveau drivers which cannot be loaded at the same time as the proprietary drivers, and cannot be unloaded at runtime because of KMS. You need to blacklist it under <code>/etc/modprobe.d/</code>.}}<br />
<br />
{{fancynote|For an overview of other kernel options for Funtoo Linux, see [[Funtoo Linux Kernels]]. There may be modules that the Debian kernel doesn't include, a situation where [http://www.funtoo.org/wiki/Funtoo_Linux_Kernels#Using_Debian-Sources_with_Genkernel genkernel] would be useful. Also be sure to see [[:Category:Hardware Compatibility|hardware compatibility]] information.}}<br />
<br />
Once <code>emerge</code> completes, you'll have a brand new kernel and initramfs installed to <code>/boot</code>, plus kernel headers installed in <code>/usr/src/linux</code>, and you'll be ready to configure the boot loader to load these to boot your Funtoo Linux system.</div>Shamus397https://www.funtoo.org/index.php?title=Package:Hydrogen&diff=7228Package:Hydrogen2014-11-30T16:09:00Z<p>Shamus397: </p>
<hr />
<div>{{Ebuild<br />
|Summary=A high quality drum synthesizer and sequencer.<br />
|CatPkg=media-sound/hydrogen<br />
|Maintainer=<br />
|Homepage=http://www.hydrogen-music.org<br />
}}<br />
<br />
Hydrogen is a high quality, sample based drum synthesizer and pattern based drum sequencer. It can utilize JACK transport as either a slave or master. Highly recommended!<br />
<br />
{{Note|This page is a stub that needs expansion!}}<br />
{{EbuildFooter}}</div>Shamus397https://www.funtoo.org/index.php?title=Package:JACK_Audio_Connection_Kit&diff=7227Package:JACK Audio Connection Kit2014-11-30T16:00:09Z<p>Shamus397: Replaced content with "{{Ebuild |Summary=A sophisticated audio routing and mixing application. |CatPkg=media-sound/jack-audio-connection-kit |Maintainer= |Homepage=http://www.jackaudio.org }} JA..."</p>
<hr />
<div>{{Ebuild<br />
|Summary=A sophisticated audio routing and mixing application.<br />
|CatPkg=media-sound/jack-audio-connection-kit<br />
|Maintainer=<br />
|Homepage=http://www.jackaudio.org<br />
}}<br />
JACK is an acronym for Jack Audio Connection Kit. It is a low latency audio server mainly utilized by pro audio software.<br />
<br />
For users that require low latency when running JACK, see the following [[Kernel/configs/realtime|kernel configuration guide]].<br />
{{EbuildFooter}}</div>Shamus397https://www.funtoo.org/index.php?title=Kernel/configs/realtime&diff=7226Kernel/configs/realtime2014-11-30T15:56:45Z<p>Shamus397: Created page with "{{Note|1= This page needs cleanup (blatantly stolen from http://proaudio.tuxfamily.org/wiki/index.php?title=DAW_Digital_Audio_Workstation which is CC:BY:SA). Bad spelling and..."</p>
<hr />
<div>{{Note|1=<br />
This page needs cleanup (blatantly stolen from http://proaudio.tuxfamily.org/wiki/index.php?title=DAW_Digital_Audio_Workstation which is CC:BY:SA). Bad spelling and grammar abound.}}<br />
<br />
===Instructions for 3.x Kernels===<br />
<br />
With the current 3.x kernels series, we have one more possibility to get real-time operations to work: Control Groups, or cgroups in short. This method is not available with the rt-kernel.<br />
<br />
For a general introduction, see [http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt cgroups kernel documentation].<br />
<br />
From it: "Control Groups provide a mechanism for aggregating/partitioning sets of tasks, and all their future children, into hierarchical groups with specialized behaviour."<br />
<br />
This is exactly what the real-time patch is doing: it provides a mechanism for aggregating the audio tasks, and for attributing them a higher priority than the other tasks. The same (and much more) can be done with the Control Groups, this with any recent kernel.<br />
<br />
On the long run, I think many of us will use a vanilla or gentoo kernel with an audio related cgroups set-up. But the rt kernel will remain in use, firstly because it has proven to be a good working solution, secondly because the developers of the rt patch will continue to experiment new solutions, and thirdly because cgroups adds a slight scheduling overhead, and some of us don't want it.<br />
<br />
For a jack related explanation, see [http://trac.jackaudio.org/wiki/Cgroups Some notes on CGroups].<br />
<br />
====RT scheduling cpu bandwidth and cgroups====<br />
In the kernel configuration, the minimal and sufficient cgroups set-up to get RT scheduling is:<br />
<br />
General setup ---><br />
[*] Control Group support ---><br />
[*] Group CPU scheduler ---><br />
[*] Group scheduling for SCHED_RR/FIFO<br />
<br />
As you can see in its help, this last option will give us CONFIG_RT_GROUP_SCHED. With this, we get access to RT scheduling cpu bandwidth controlled via cgroups. The root cgroup has this setup correctly. Remember, RT operations is all about bandwidth allocation of resources, more bandwidth for some tasks imply less bandwidth and responsiveness for the others.<br />
<br />
====cgroups set-up====<br />
<br />
We also need to install dev-libs/libcgroup, which provide tools and libraries to configure and manage kernel Control Groups.<br />
<br />
emerge libcgroup<br />
<br />
However when libcgroup is installed and the cgconfig service has been started, it creates a "sysdefault" cgroup and moves all tasks over there. The sysdefault group does not have RT bandwidth assigned to it. In this case jackd can not be started.<br />
<br />
There are several methods to configure cgroups for our purpose ([http://trac.jackaudio.org/wiki/Cgroups Some notes on CGroups]).<br />
I started with the method 2, but it was necessary to add a namespace section. In consequence, the following set-up is a mix of method 2 and 3.<br />
<br />
Edit /etc/cgroups/cgconfig.conf as follow:<br />
<br />
namespace {<br />
cpu = /;<br />
}<br />
<br />
group rtaudio {<br />
perm {<br />
task {<br />
uid = root;<br />
gid = audio;<br />
}<br />
admin {<br />
uid = root;<br />
gid = root;<br />
}<br />
}<br />
cpu {<br />
cpu.rt_runtime_us = 950000;<br />
}<br />
}<br />
<br />
We create here a kernel cgroup named rtaudio. Root can manage it. The users in the audio group can use it. We use rtaudio to define the processor use of the RT processes. The members of the rtaudio cgroup (the RT threads of the programs which are member of rtaudio) can use the processor during 950000 us per second, the other tasks get the remaining time, 50000 us.<br />
<br />
At that time, we need to explicitly add the programs that must get RT scheduling. For that, edit /etc/cgroups/cgrules.conf:<br />
<br />
# One of the following line is needed for jack<br />
#@audio:jackd cpu rtaudio/<br />
@audio:jackdbus cpu rtaudio/<br />
# Comment the 2 following lines if not using snd-aloop<br />
@audio:alsa_in cpu rtaudio/<br />
@audio:alsa_out cpu rtaudio/<br />
# Add one line for each RT software<br />
@audio:mplayer cpu rtaudio/<br />
@audio:ardour cpu rtaudio/<br />
@audio:jamin cpu rtaudio/<br />
<br />
You must add one line per application you want to be in the rtaudio cgroup. In the future, jack will provide a mechanism to move the RT threads of its clients into the cgroup of jackd.<br />
<br />
We must configure PAM in /etc/security/limits.conf:<br />
@audio - rtprio 99<br />
@audio - memlock unlimited<br />
<br />
Starting cgroups with our configuration:<br />
# /etc/init.d/cgred start<br />
* Starting cgconfig service ... [ ok ]<br />
* Starting CGroup Rules Engine Daemon ... [ ok ]<br />
<br />
Only the new processes will be managed by cgroups. It is best to start it at boot time:<br />
rc-update add cgred default<br />
<br />
====Testing cgroups====<br />
To test your set-up, you can use the 2 following small scripts, findrtp and findrtt.<br />
<br />
findrtt will output the running programs which are member of rtaudio. findrtt will output all their threads.<br />
<br />
findrtp<br />
<br />
#!/bin/sh<br />
for i in `cat /sys/fs/cgroup/cpu//rtaudio/cgroup.procs`;<br />
do echo "Found pid $i which correspond at `cat /proc/$i/cmdline`";<br />
done<br />
<br />
and<br />
<br />
findrtt<br />
<br />
#!/bin/sh<br />
for i in `cat /sys/fs/cgroup/cpu//rtaudio/tasks`;<br />
do echo "Find pid $i which correspond to `cat /proc/$i/cmdline`";<br />
done<br />
<br />
Save them in your path and make them executable.<br />
<br />
Run them:<br />
# findrtp<br />
Trouvé le pid 1846 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2123 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2124 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2162 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2259 qui correspond à mplayerdvb://2@<br />
<br />
# findrtt<br />
Trouvé le pid 1846 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2116 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2117 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2118 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2119 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2123 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2124 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2128 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2129 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2130 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2131 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2162 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2170 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2171 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2172 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2259 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2339 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2340 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2341 qui correspond à mplayerdvb://2@<br />
<br />
To see which threads are RT, we can use ps:<br />
ps -eLo rtprio,pri,cgroup,class,pid,pcpu,%mem,user,comm --sort pri|less<br />
RTPRIO PRI CGROUP CLS PID %CPU %MEM USER COMMAND<br />
...<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
10 50 2:cpu:/rtaudio FF 2613 0.4 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
...<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
5 45 2:cpu:/rtaudio FF 3642 0.5 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
5 45 2:cpu:/rtaudio FF 3643 0.5 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
5 45 2:cpu:/rtaudio FF 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 30170 6.1 1.4 dom mplayer<br />
- 19 2:cpu:/rtaudio TS 30170 0.0 1.4 dom mplayer<br />
- 19 2:cpu:/rtaudio TS 30170 0.0 1.4 dom mplayer<br />
5 45 2:cpu:/rtaudio FF 30170 0.1 1.4 dom mplayer<br />
<br />
The FF threads are the real-time ones. We will see the same result with htop, but with other priority numbers (I prefer htop).<br />
<br />
Another test is to lower jack latency. Run qjackctl and play with the parameters. With the Control Groups, I can lower jack latency with the gentoo-sources from 42,7 msec (1024 Frames/Period, 48kHz, 2 Periods/Buffer) to 0,667 msec (16 Frames/Period) without more xruns (only at applications start-up), which is as good as with the rt-sources.</div>Shamus397https://www.funtoo.org/index.php?title=Package:Virtualjaguar&diff=7225Package:Virtualjaguar2014-11-30T15:51:21Z<p>Shamus397: </p>
<hr />
<div>{{Ebuild<br />
|Summary=A cross-platform Atari Jaguar emulator.<br />
|CatPkg=games-emulation/virtualjaguar<br />
|Maintainer=<br />
|Homepage=http://icculus.org/virtualjaguar<br />
}}<br />
<br />
[http://icculus.org/virtualjaguar Virtual Jaguar] is a cross-platform Atari Jaguar emulator with a Qt UI. Currently the only one still in active development, it is being utilized by developers of Jaguar software in conjunction with real hardware tools like the [http://www.harmlesslion.com/cgi-bin/showprog.cgi?search=skunkboard Skunkboard]. Also the only Jaguar emulator that comes with it's own pack-in title: [http://reboot.atari.org/new-reboot/downfall.html Downfall]. One of the stated goals of the project is to increase the compatibility as much as possible; as a result, speed is sometimes sacrificed.<br />
<br />
=== Features ===<br />
* Multi-platform (currently Linux, Windows, and MacOS)<br />
* Gamepad support<br />
* Full screen support<br />
* Good compatibility with existing Jaguar software<br />
* Built-in facilities to assist developers in creating new software<br />
<br />
=== Technical Features ===<br />
* Partially multithreaded implementation of processor cores<br />
* Customized version of the UAE 68000 core<br />
* GUI is decoupled from emulator core</div>Shamus397https://www.funtoo.org/index.php?title=Package:Hydrogen&diff=7176Package:Hydrogen2014-11-27T06:04:18Z<p>Shamus397: Hydrogen is a high quality drum synthesizer and sequencer.</p>
<hr />
<div>== Hydrogen ==<br />
<br />
Hydrogen is a high quality, sample based drum synthesizer and pattern based drum sequencer. It can utilize JACK transport as either a slave or master. Highly recommended!<br />
<br />
This page is a stub that needs expansion!</div>Shamus397https://www.funtoo.org/index.php?title=Package:JACK_Audio_Connection_Kit&diff=7175Package:JACK Audio Connection Kit2014-11-27T05:50:01Z<p>Shamus397: Jack Audio Connection Kit</p>
<hr />
<div>== JACK ==<br />
<br />
JACK is an acronym for Jack Audio Connection Kit. It is a low latency audio server mainly utilized by pro audio software.<br />
<br />
Note: This page needs cleanup. The following probably needs to go into it's own page on the wiki! (blatantly stolen from http://proaudio.tuxfamily.org/wiki/index.php?title=DAW_Digital_Audio_Workstation which is CC:BY:SA)<br />
<br />
===Instructions for 3.x Kernels===<br />
<br />
With the current 3.x kernels series, we have one more possibility to get real-time operations to work: Control Groups, or cgroups in short. This method is not available with the rt-kernel.<br />
<br />
For a general introduction, see [http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt cgroups kernel documentation].<br />
<br />
From it: "Control Groups provide a mechanism for aggregating/partitioning sets of tasks, and all their future children, into hierarchical groups with specialized behaviour."<br />
<br />
This is exactly what the real-time patch is doing: it provide a mechanism for aggregating the audio tasks, and for attributing them a higher priority than the other tasks. The same (and much more) can be done with the Control Groups, this with any recent kernel.<br />
<br />
On the long run, I think many of us will use a vanilla or gentoo kernel with an audio related cgroups set-up. But the rt kernel will remain in use, firstly because it have proven to be a good working solution, secondly because the developers of the rt patch will continue to experiment new solutions, and thirdly because cgroups add a slight scheduling overhead, and some of us don't want it.<br />
<br />
For a jack related explanation, see [http://trac.jackaudio.org/wiki/Cgroups Some notes on CGroups].<br />
<br />
====RT scheduling cpu bandwidth and cgroups====<br />
In the kernel configuration, the minimal and sufficient cgroups set-up to get RT scheduling is:<br />
<br />
General setup ---><br />
[*] Control Group support ---><br />
[*] Group CPU scheduler ---><br />
[*] Group scheduling for SCHED_RR/FIFO<br />
<br />
As you can see in its help, this last option will give us CONFIG_RT_GROUP_SCHED. With this, we get access to RT scheduling cpu bandwidth controlled via cgroups. The root cgroup has this setup correctly. Remember, RT operations is all about bandwidth allocation of resources, more bandwidth for some task imply less bandwidth and responsiveness for the other.<br />
<br />
====cgroups set-up====<br />
<br />
We also need to install dev-libs/libcgroup, which provide tools and libraries to configure and manage kernel Control Groups.<br />
<br />
emerge libcgroup<br />
<br />
However when libcgroup is installed and the cgconfig service has been started, it creates a "sysdefault" cgroup and moves all tasks over there. The sysdefault group does not have RT bandwidth assigned to it. In this case jackd can not be started.<br />
<br />
It is several methods to configure cgroups for our purpose ([http://trac.jackaudio.org/wiki/Cgroups Some notes on CGroups]).<br />
I started with the method 2, but it was necessary to add a namespace section. In consequence, the following set-up is a mix of method 2 and 3.<br />
<br />
Edit /etc/cgroups/cgconfig.conf as follow:<br />
<br />
namespace {<br />
cpu = /;<br />
}<br />
<br />
group rtaudio {<br />
perm {<br />
task {<br />
uid = root;<br />
gid = audio;<br />
}<br />
admin {<br />
uid = root;<br />
gid = root;<br />
}<br />
}<br />
cpu {<br />
cpu.rt_runtime_us = 950000;<br />
}<br />
}<br />
<br />
We create here a kernel cgroup named rtaudio. Root can manage it. The users in the audio group can use it. We use rtaudio to define the processor use of the RT processes. The members of the rtaudio cgroup (the RT threads of the programs which are member of rtaudio) can use the processor during 950000 us per second, the other tasks get the remaining time, 50000 us.<br />
<br />
At that time, we need to explicitly add the programs that must get RT scheduling. For that, edit /etc/cgroups/cgrules.conf:<br />
<br />
# One of the following line is needed for jack<br />
#@audio:jackd cpu rtaudio/<br />
@audio:jackdbus cpu rtaudio/<br />
# Comment the 2 following lines if not using snd-aloop<br />
@audio:alsa_in cpu rtaudio/<br />
@audio:alsa_out cpu rtaudio/<br />
# Add one line for each RT software<br />
@audio:mplayer cpu rtaudio/<br />
@audio:ardour cpu rtaudio/<br />
@audio:jamin cpu rtaudio/<br />
<br />
You must add one line per application you want to be in the rtaudio cgroup. In the future, jack will provide a mechanism to move the RT threads of its clients into the cgroup of jackd.<br />
<br />
We must configure PAM in /etc/security/limits.conf:<br />
@audio - rtprio 99<br />
@audio - memlock unlimited<br />
<br />
Starting chroups with our configuration:<br />
# /etc/init.d/cgred start<br />
* Starting cgconfig service ... [ ok ]<br />
* Starting CGroup Rules Engine Daemon ... [ ok ]<br />
<br />
Only the new processes will be managed by cgroups. It is best to start it at boot time:<br />
rc-update add cgred default<br />
<br />
====Testing cgroups====<br />
To test your set-up, you can use the 2 following small scripts, findrtp and findrtt.<br />
<br />
findrtt will output the running programs which are member of rtaudio. findrtt will output all their threads.<br />
<br />
findrtp<br />
<br />
#!/bin/sh<br />
for i in `cat /sys/fs/cgroup/cpu//rtaudio/cgroup.procs`;<br />
do echo "Found pid $i which correspond at `cat /proc/$i/cmdline`";<br />
done<br />
<br />
and<br />
<br />
findrtt<br />
<br />
#!/bin/sh<br />
for i in `cat /sys/fs/cgroup/cpu//rtaudio/tasks`;<br />
do echo "Find pid $i which correspond to `cat /proc/$i/cmdline`";<br />
done<br />
<br />
Save them in your path and make them executable.<br />
<br />
Run them:<br />
# findrtp<br />
Trouvé le pid 1846 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2123 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2124 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2162 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2259 qui correspond à mplayerdvb://2@<br />
<br />
# findrtt<br />
Trouvé le pid 1846 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2116 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2117 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2118 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2119 qui correspond à /usr/bin/jackdbusauto<br />
Trouvé le pid 2123 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2124 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2128 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2129 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2130 qui correspond à /usr/bin/alsa_out-jploop-dploop-q1<br />
Trouvé le pid 2131 qui correspond à /usr/bin/alsa_in-jcloop-dcloop-q1<br />
Trouvé le pid 2162 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2170 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2171 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2172 qui correspond à timidity-iA-B2,8-Oj-EFreverb=0-s48000<br />
Trouvé le pid 2259 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2339 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2340 qui correspond à mplayerdvb://2@<br />
Trouvé le pid 2341 qui correspond à mplayerdvb://2@<br />
<br />
To see which threads are RT, we can use ps:<br />
ps -eLo rtprio,pri,cgroup,class,pid,pcpu,%mem,user,comm --sort pri|less<br />
RTPRIO PRI CGROUP CLS PID %CPU %MEM USER COMMAND<br />
...<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
10 50 2:cpu:/rtaudio FF 2613 0.4 1.0 dom jackdbus<br />
- 19 2:cpu:/rtaudio TS 2613 0.0 1.0 dom jackdbus<br />
...<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3642 0.0 1.0 dom alsa_out<br />
5 45 2:cpu:/rtaudio FF 3642 0.5 1.0 dom alsa_out<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3643 0.0 1.0 dom alsa_in<br />
5 45 2:cpu:/rtaudio FF 3643 0.5 1.0 dom alsa_in<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 3664 0.0 1.3 dom timidity<br />
5 45 2:cpu:/rtaudio FF 3664 0.0 1.3 dom timidity<br />
- 19 2:cpu:/rtaudio TS 30170 6.1 1.4 dom mplayer<br />
- 19 2:cpu:/rtaudio TS 30170 0.0 1.4 dom mplayer<br />
- 19 2:cpu:/rtaudio TS 30170 0.0 1.4 dom mplayer<br />
5 45 2:cpu:/rtaudio FF 30170 0.1 1.4 dom mplayer<br />
<br />
The FF threads are the real-time one. We will see the same result with htop, but with other priority numbers (I prefer htop).<br />
<br />
Another test is to lower jack latency. Run qjackctl and play with the parameters. With the Control Groups, I can lower jack latency with the gentoo-sources from 42,7 msec (1024 Frames/Period, 48kHz, 2 Periods/Buffer) to 0,667 msec (16 Frames/Period) without more xruns (only at applications start-up), which is as good than with the rt-sources.</div>Shamus397https://www.funtoo.org/index.php?title=Package:Virtualjaguar&diff=6710Package:Virtualjaguar2014-11-05T16:03:22Z<p>Shamus397: About the virtualjaguar package</p>
<hr />
<div>=== Brief Synopsis ===<br />
[http://icculus.org/virtualjaguar Virtual Jaguar] is a cross-platform Atari Jaguar emulator with a Qt UI. Currently the only one still in active development, it is being utilized by developers of Jaguar software in conjunction with real hardware tools like the [http://www.harmlesslion.com/cgi-bin/showprog.cgi?search=skunkboard Skunkboard]. Also the only Jaguar emulator that comes with it's own pack-in title: [http://reboot.atari.org/new-reboot/downfall.html Downfall]. One of the stated goals of the project is to increase the compatibility as much as possible; as a result, speed is sometimes sacrificed.<br />
<br />
=== Features ===<br />
* Multi-platform (currently Linux, Windows, and MacOS)<br />
* Gamepad support<br />
* Full screen support<br />
* Good compatibility with existing Jaguar software<br />
* Built-in facilities to assist developers in creating new software<br />
<br />
=== Technical Features ===<br />
* Partially multithreaded implementation of processor cores<br />
* Customized version of the UAE 68000 core<br />
* GUI is decoupled from emulator core</div>Shamus397https://www.funtoo.org/index.php?title=Talk:Funtoo_ARMv7&diff=5151Talk:Funtoo ARMv72014-09-05T15:23:49Z<p>Shamus397: Created page with "This is not sufficient to get things to work with crossdev. Having armv7 in the tuple is not enough; this causes errors to occur when trying to build stage 1 gcc. In my case,..."</p>
<hr />
<div>This is not sufficient to get things to work with crossdev. Having armv7 in the tuple is not enough; this causes errors to occur when trying to build stage 1 gcc. In my case, I had a Freescale i.MX6 (ARMv7), and the tuple I had to use was armv7a-softfloat-linux-gnueabi.<br />
<br />
Seems that you *must* specify the exact core you're using; maybe a table would help here?</div>Shamus397