https://wiki.archlinux.org/api.php?action=feedcontributions&user=Lfxgroove&feedformat=atomArchWiki - User contributions [en]2024-03-28T14:03:08ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Virtual_user_mail_system_with_Postfix,_Dovecot_and_Roundcube&diff=328436Virtual user mail system with Postfix, Dovecot and Roundcube2014-08-04T08:19:24Z<p>Lfxgroove: Add a notice about postfixadmin usage as using the currently given config for postfix wouldn't work with postfixadmin.</p>
<hr />
<div>[[Category:Mail Server]]<br />
{{Related articles start}}<br />
{{Related|Postfix}}<br />
{{Related|Courier MTA}}<br />
{{Related|OpenDKIM}}<br />
{{Related articles end}}<br />
This article describes how to set up a complete virtual user mail system on an Arch Linux system in the simplest manner possible. However, since a mail system consists of many complex components, quite a bit of configuration will still be necessary. <br />
<br />
Roughly, the components used in this article are Postfix as the mail server, Dovecot as the IMAP server, Roundcube as the webmail interface and PostfixAdmin as the administration interface to manage it all.<br />
<br />
In the end, the provided solution will allow you to use the best currently available security mechanisms, you will be able to send mails using SMTP and SMTPS and receive mails using POP3, POP3S, IMAP and IMAPS. Additionally, configuration will be easy thanks to PostfixAdmin and users will be able to login using Roundcube. What a deal!<br />
<br />
== Installation ==<br />
Before you start, you must have both a working MySQL server as described in [[MySQL]] and a working Postfix server as described in [[Postfix]].<br />
<br />
[[pacman|Install]] the {{Pkg|dovecot}} and {{Pkg|roundcubemail}} packages from the [[official repositories]].<br />
<br />
== Configuration ==<br />
=== User ===<br />
For security reasons, a new user should be created to store the mails:<br />
# groupadd -g 5000 vmail<br />
# useradd -u 5000 -g vmail -s /usr/bin/nologin -d /home/vmail -m vmail<br />
A gid and uid of 5000 is used in both cases so that we do not run into conflicts with regular users. All your mail will then be stored in {{ic|/home/vmail}}. You could change the home directory to something like {{ic|/var/mail/vmail}} but be careful to change this in any configuration below as well.<br />
<br />
=== Database ===<br />
You will need to create an empty database and corresponding user. In this article, the user ''postfix_user'' will have read/write access to the database ''postfix_db'' using ''hunter2'' as password. You are expected to create the database and user yourself, and give the user permission to use the database, as shown in the following code.<br />
<br />
{{hc|$ mysql -u root -p|<br />
CREATE DATABASE postfix_db;<br />
USE postfix_db;<br />
CREATE USER postfix_user@localhost IDENTIFIED BY 'hunter2';<br />
GRANT ALL ON postfix_db.* TO postfix_user@localhost;<br />
FLUSH PRIVILEGES;<br />
}}<br />
<br />
Now you can either let PostfixAdmin create the needed tables and create the users in there, or do it manually.<br />
<br />
==== PostfixAdmin ====<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
==== Manual database management ====<br />
If do not want to use PostfixAdmin to create and manage your user/domain tables, you can do it manually:<br />
<br />
To create the tables:<br />
{{bc|<br />
CREATE TABLE `domains` (<br />
`domain` varchar(50) NOT NULL default "",<br />
PRIMARY KEY (`domain`),<br />
UNIQUE KEY `domain` (`domain`)<br />
);<br />
<br />
<br />
CREATE TABLE `forwardings` (<br />
`source` varchar(80) NOT NULL default "",<br />
`destination` text NOT NULL,<br />
PRIMARY KEY (`source`)<br />
);<br />
<br />
CREATE TABLE `users` (<br />
`email` varchar(80) NOT NULL default "",<br />
`password` varchar(20) NOT NULL default "",<br />
`quota` varchar(20) NOT NULL default '20971520',<br />
`domain` varchar(255) NOT NULL default "",<br />
UNIQUE KEY `email` (`email`)<br />
);<br />
}}<br />
<br />
To add a domain:<br />
<br />
INSERT INTO `domains` VALUES ('virtualdomain.tld');<br />
<br />
To add a user with encrypted password "secret":<br />
<br />
INSERT INTO `users` VALUES ('cactus@virtualdomain.tld', ENCRYPT('secret'), '20971520', 'virtualdomain.tld');<br />
<br />
=== SSL certificate ===<br />
You will need a SSL certificate for SMTPS. If you do not have one, create one:<br />
# cd /etc/ssl/private/<br />
# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out server.key<br />
# chmod 400 server.key<br />
# openssl req -new -key server.key -out server.csr<br />
# openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
# chmod 444 server.crt<br />
<br />
=== Postfix ===<br />
Enable secure SMTP as described in [[Postfix#Secure SMTP]].<br />
<br />
{{Note|If you want to use [[Postfix#PostfixAdmin|PostfixAdmin]] as well, please see the {{ic|<nowiki>/path/to/postfixadmin/DOCUMENTS/POSTFIX_CONF.txt</nowiki>}} file and disregard this section.}}<br />
<br />
To {{ic|/etc/postfix/main.cf}} append:<br />
relay_domains = *<br />
virtual_alias_maps = proxy:mysql:/etc/postfix/virtual_alias_maps.cf<br />
virtual_mailbox_domains = proxy:mysql:/etc/postfix/virtual_mailbox_domains.cf<br />
virtual_mailbox_maps = proxy:mysql:/etc/postfix/virtual_mailbox_maps.cf<br />
virtual_mailbox_base = /home/vmail<br />
virtual_mailbox_limit = 512000000<br />
virtual_minimum_uid = 5000<br />
virtual_transport = virtual<br />
virtual_uid_maps = static:5000<br />
virtual_gid_maps = static:5000<br />
local_transport = virtual<br />
local_recipient_maps = $virtual_mailbox_maps<br />
transport_maps = hash:/etc/postfix/transport<br />
<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = /var/run/dovecot/auth-client<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_sasl_security_options = noanonymous<br />
smtpd_sasl_tls_security_options = $smtpd_sasl_security_options<br />
smtpd_tls_auth_only = yes<br />
smtpd_tls_cert_file = /etc/ssl/private/server.crt<br />
smtpd_tls_key_file = /etc/ssl/private/server.key<br />
smtpd_sasl_local_domain = $mydomain<br />
broken_sasl_auth_clients = yes<br />
smtpd_tls_loglevel = 1<br />
<br />
{{Warning|{{ic|<nowiki>relay_domains = *</nowiki>}} might be a bad idea (see http://www.postfix.org/BASIC_CONFIGURATION_README.html#relay_to). You usually do not want postfix to forward mail from strangers.}} <br />
<br />
{{ic|virtual_mailbox_domains}} is a list of the domains that you want to receive mail for. This CANNOT contain the domain that is set in {{ic|mydestination}}. That is why we left {{ic|mydestination}} to be localhost only.<br />
<br />
{{ic|virtual_mailbox_maps}} will contain the info about the virtual users and their mailbox locations. We are using a hash file to store the more permanent maps, and these will override the forwards in the MySQL database.<br />
<br />
{{ic|virtual_mailbox_base}} is the base directory where the virtual mailboxes will be stored.<br />
<br />
The gid and uid maps are the real system user account that the virtual mail will be owned by. This is for storage purposes. Since we will be using a web interface, and do not want people accessing this by any other means, we will be creating this account later with no login access.<br />
<br />
This references a lot of files that do not even exist yet. Create them with the following contents:<br />
<br />
{{hc|/etc/postfix/virtual_alias_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = domains<br />
select_field = virtual<br />
where_field = domain<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_domains.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = forwardings<br />
select_field = destination<br />
where_field = source<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = users<br />
select_field = concat(domain,'/',email,'/')<br />
where_field = email<br />
</nowiki>}}<br />
<br />
{{Note|Instead of having a directory structure something like ''/home/vmail/example.com/user@example.com'' you can have cleaner subdirectories (without the additional domain name) by replacing ''select_field'' and ''where_field'' with:<br />
{{bc|1=query = SELECT CONCAT(SUBSTRING_INDEX(email,'@',-1),'/',SUBSTRING_INDEX(email,'@',1),'/') FROM users WHERE email='%s'}}<br />
}}<br />
<br />
Run ''postmap'' on ''transport'' to generate its db:<br />
# postmap /etc/postfix/transport<br />
<br />
=== Dovecot ===<br />
Start by creating a new {{ic|/etc/dovecot/dovecot.conf}} with the following contents:<br />
protocols = imap<br />
auth_mechanisms = plain<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
userdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
<br />
service auth {<br />
unix_listener auth-client {<br />
group = postfix<br />
mode = 0660<br />
user = postfix<br />
}<br />
user = root<br />
}<br />
<br />
mail_home = /home/vmail/%d/%u<br />
mail_location = maildir:~<br />
<br />
ssl_cert = </etc/ssl/private/server.crt<br />
ssl_key = </etc/ssl/private/server.key<br />
<br />
If you instead want to modify {{ic|dovecot.conf.sample}}, beware that the default configuration file imports the content of {{ic|conf.d/*.conf}}. Those files call other files that aren't present in our configuration.<br />
<br />
See http://wiki2.dovecot.org/Variables for the docevot variables %d and %u.<br />
<br />
Now obviously we also need the {{ic|/etc/dovecot/dovecot-sql.conf}} we just referenced in the config above. Go ahead and create a {{ic|/etc/dovecot/dovecot-sql.conf}} with these contents:<br />
driver = mysql<br />
connect = host=localhost dbname=postfix_db user=postfix_user password=hunter2<br />
# The new name for MD5 is MD5-CRYPT so you might need to change this depending on version<br />
default_pass_scheme = MD5-CRYPT<br />
# Get the mailbox<br />
user_query = SELECT '/home/vmail/%d/%u' as home, 'maildir:/home/vmail/%d/%u' as mail, 5000 AS uid, 5000 AS gid, concat('dirsize:storage=', quota) AS quota FROM mailbox WHERE username = '%u' AND active = '1'<br />
# Get the password<br />
password_query = SELECT username as user, password, '/home/vmail/%d/%u' as userdb_home, 'maildir:/home/vmail/%d/%u' as userdb_mail, 5000 as userdb_uid, 5000 as userdb_gid FROM mailbox WHERE username = '%u' AND active = '1'<br />
# If using client certificates for authentication, comment the above and uncomment the following<br />
#password_query = SELECT null AS password, ‘%u’ AS user<br />
<br />
=== PostfixAdmin ===<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
=== Roundcube ===<br />
Roundcube needs a separate database to work. You'll need to provide information about the database during installation. Make sure that the {{ic|pdo_mysql.so}} extension is uncommented in your {{ic|php.ini}} file. Also check the {{ic|.htaccess}} for access restrictions. Assuming that localhost is your current host, navigate a browser to ''http://localhost/roundcube/installer/'' and follow the instructions. You should not use the same database for Roundcube that you already used for PostfixAdmin: create a second database "roundcube_db" and a "roundcube_user" for use with Roundcube. <br />
<br />
While running the installer, make sure to address the IMAP host with '''ssl://localhost/''' or '''tls://localhost/''' instead of just '''localhost'''. Use port 993. Likewise with SMTP, make sure to provide '''ssl://localhost/''' on port 465 if you used the wrapper mode and '''tls://localhost/''' on port 587 if you used the proper TLS mode. See [[#Postfix|here]] for an explanation on that.<br />
<br />
The post install process is similar to any other webapps like [[PhpMyAdmin]] or PostFixAdmin. The configuration file is {{ic|/etc/webapps/roundcubemail/config/config.inc.php}} which works as an override over {{ic|default.inc.php}}.<br />
<br />
If you are using Apache, copy the example configuration file to your webserver configuration directory.<br />
# cp /etc/webapps/roundcubemail/apache.conf /etc/httpd/conf/extra/httpd-roundcubemail.conf<br />
<br />
Add the include line in {{ic|/etc/httpd/conf/httpd.conf}}<br />
Include conf/extra/httpd-roundcubemail.conf<br />
To let users change their passwords from within Roundcube, do the following:<br />
<br />
Enable password plugin by adding this line to {{ic|/etc/webapps/roundcubemail/config/config.inc.php}}:<br />
$rcmail_config['plugins'] = array('password');<br />
<br />
Configure password plugin in {{ic|/usr/share/webapps/roundcubemail/plugins/password/config.inc.php}}:<br />
$config['password_driver'] = 'sql';<br />
$config['password_db_dsn'] = 'mysql://postfix_database_user:password@localhost/postfix_database_name';<br />
$config['password_query'] = 'UPDATE mailbox SET password=%c WHERE username=%u';<br />
<br />
== Fire it up ==<br />
Since now hopefully everything is set up correctly, all necessary daemons should be started for a test run:<br />
# systemctl start postfix dovecot<br />
<br />
Now for testing purposes, create a domain and mail account in PostfixAdmin. Try to login to this account using Roundcube. Now send yourself a mail.<br />
<br />
== Optional Items ==<br />
Although these items are not required, they definitely add more completeness to your setup<br />
<br />
=== Quota ===<br />
To enable mailbox quota support by dovecot, do the following: <br />
*First add the following lines to /etc/dovecot.conf<br />
dict {<br />
quotadict = mysql:/etc/dovecot/dovecot-dict-sql.conf.ext<br />
}<br />
service dict {<br />
unix_listener dict {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
user = root<br />
}<br />
service quota-warning {<br />
executable = script /usr/local/bin/quota-warning.sh<br />
user = vmail<br />
unix_listener quota-warning {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
} <br />
mail_plugins=quota<br />
protocol pop3 {<br />
mail_plugins = quota<br />
pop3_client_workarounds = outlook-no-nuls oe-ns-eoh<br />
pop3_uidl_format = %08Xu%08Xv<br />
}<br />
protocol lda {<br />
mail_plugins = quota<br />
postmaster_address = postmaster@yourdomain.com<br />
}<br />
protocol imap {<br />
mail_plugins = $mail_plugins imap_quota<br />
mail_plugin_dir = /usr/lib/dovecot/modules<br />
}<br />
plugin {<br />
quota = dict:User quota::proxy::quotadict<br />
quota_rule2 = Trash:storage=+10%%<br />
quota_warning = storage=95%% quota-warning 95 %u<br />
quota_warning2 = storage=80%% quota-warning 80 %u<br />
quota_warning3 = -storage=100%% quota-warning below 100 %u # user is no longer over quota<br />
<br />
*Create a new file /etc/dovecot/dovecot-dict-sql.conf.ext with the following code:<br />
connect = host=localhost dbname=yourdb user=youruser password=yourpassword<br />
map {<br />
pattern = priv/quota/storage<br />
table = quota2<br />
username_field = username<br />
value_field = bytes<br />
}<br />
map {<br />
pattern = priv/quota/messages<br />
table = quota2<br />
username_field = username<br />
value_field = messages<br />
}<br />
*Create a warning script /usr/local/bin/quota-warning.sh and make sure it is executable.<br />
#!/bin/sh<br />
PERCENT=$1<br />
USER=$2<br />
cat << EOF | /usr/lib/dovecot/dovecot-lda -d $USER -o "plugin/quota=maildir:User quota:noenforcing"<br />
From: postmaster@yourdomain.com<br />
Subject: quota warning<br />
<br />
THIS MESSAGE IS AUTOMATICALLY GENERATED BY THE MAIL SYSTEM. DO NOT REPLY TO IT.<br />
<br />
Dear User,<br />
Your mailbox is now $PERCENT% full. Please remove some mails from the server.<br />
Regards,<br />
Postmaster<br />
EOF<br />
<br />
*Edit the user_query line and add iterat_query in dovecot-sql.conf as following:<br />
user_query = SELECT '/home/vmail/%d/%u' as home, 'maildir:/home/vmail/%d/%u' as mail, 5000 AS uid, 5000 AS gid, concat('*:bytes=', quota) AS quota_rule FROM mailbox WHERE username = '%u' AND active = '1'<br />
iterate_query = SELECT username AS user FROM mailbox<br />
*Set up LDA as described above under SpamAssassin. If you're not using SpamAssassin, the pipe should look like this in /etc/postfix/master.cf :<br />
dovecot unix - n n - - pipe<br />
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient}<br />
As above activate it in Postfix main.cf<br />
virtual_transport = dovecot<br />
*You can set up quota per each mailbox in postfixadmin. Make sure the relevant lines in config.inc.php look like this:<br />
$CONF['quota'] = 'YES';<br />
$CONF['quota_multiplier'] = '1024000';<br />
<br />
Restart postfix and dovecot services. If things go well, you should be able to list all users' quota and usage by the this command:<br />
doveadm quota get -A<br />
You should be able to see the quota in roundcube too.<br />
<br />
== Troubleshooting ==<br />
If you get errors like your imap/pop3 client failing to receive mails, take a look into your /var/log/mail.log file.<br />
It turned out that the maildir /home/vmail/mail@domain.tld is just being created if there is at least one email waiting. Otherwise there wouldn't be any need for the directory.</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Virtual_user_mail_system_with_Postfix,_Dovecot_and_Roundcube&diff=328435Virtual user mail system with Postfix, Dovecot and Roundcube2014-08-04T08:10:56Z<p>Lfxgroove: Remove quotes around password as they would get postfix to not connect to the database.</p>
<hr />
<div>[[Category:Mail Server]]<br />
{{Related articles start}}<br />
{{Related|Postfix}}<br />
{{Related|Courier MTA}}<br />
{{Related|OpenDKIM}}<br />
{{Related articles end}}<br />
This article describes how to set up a complete virtual user mail system on an Arch Linux system in the simplest manner possible. However, since a mail system consists of many complex components, quite a bit of configuration will still be necessary. <br />
<br />
Roughly, the components used in this article are Postfix as the mail server, Dovecot as the IMAP server, Roundcube as the webmail interface and PostfixAdmin as the administration interface to manage it all.<br />
<br />
In the end, the provided solution will allow you to use the best currently available security mechanisms, you will be able to send mails using SMTP and SMTPS and receive mails using POP3, POP3S, IMAP and IMAPS. Additionally, configuration will be easy thanks to PostfixAdmin and users will be able to login using Roundcube. What a deal!<br />
<br />
== Installation ==<br />
Before you start, you must have both a working MySQL server as described in [[MySQL]] and a working Postfix server as described in [[Postfix]].<br />
<br />
[[pacman|Install]] the {{Pkg|dovecot}} and {{Pkg|roundcubemail}} packages from the [[official repositories]].<br />
<br />
== Configuration ==<br />
=== User ===<br />
For security reasons, a new user should be created to store the mails:<br />
# groupadd -g 5000 vmail<br />
# useradd -u 5000 -g vmail -s /usr/bin/nologin -d /home/vmail -m vmail<br />
A gid and uid of 5000 is used in both cases so that we do not run into conflicts with regular users. All your mail will then be stored in {{ic|/home/vmail}}. You could change the home directory to something like {{ic|/var/mail/vmail}} but be careful to change this in any configuration below as well.<br />
<br />
=== Database ===<br />
You will need to create an empty database and corresponding user. In this article, the user ''postfix_user'' will have read/write access to the database ''postfix_db'' using ''hunter2'' as password. You are expected to create the database and user yourself, and give the user permission to use the database, as shown in the following code.<br />
<br />
{{hc|$ mysql -u root -p|<br />
CREATE DATABASE postfix_db;<br />
USE postfix_db;<br />
CREATE USER postfix_user@localhost IDENTIFIED BY 'hunter2';<br />
GRANT ALL ON postfix_db.* TO postfix_user@localhost;<br />
FLUSH PRIVILEGES;<br />
}}<br />
<br />
Now you can either let PostfixAdmin create the needed tables and create the users in there, or do it manually.<br />
<br />
==== PostfixAdmin ====<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
==== Manual database management ====<br />
If do not want to use PostfixAdmin to create and manage your user/domain tables, you can do it manually:<br />
<br />
To create the tables:<br />
{{bc|<br />
CREATE TABLE `domains` (<br />
`domain` varchar(50) NOT NULL default "",<br />
PRIMARY KEY (`domain`),<br />
UNIQUE KEY `domain` (`domain`)<br />
);<br />
<br />
<br />
CREATE TABLE `forwardings` (<br />
`source` varchar(80) NOT NULL default "",<br />
`destination` text NOT NULL,<br />
PRIMARY KEY (`source`)<br />
);<br />
<br />
CREATE TABLE `users` (<br />
`email` varchar(80) NOT NULL default "",<br />
`password` varchar(20) NOT NULL default "",<br />
`quota` varchar(20) NOT NULL default '20971520',<br />
`domain` varchar(255) NOT NULL default "",<br />
UNIQUE KEY `email` (`email`)<br />
);<br />
}}<br />
<br />
To add a domain:<br />
<br />
INSERT INTO `domains` VALUES ('virtualdomain.tld');<br />
<br />
To add a user with encrypted password "secret":<br />
<br />
INSERT INTO `users` VALUES ('cactus@virtualdomain.tld', ENCRYPT('secret'), '20971520', 'virtualdomain.tld');<br />
<br />
=== SSL certificate ===<br />
You will need a SSL certificate for SMTPS. If you do not have one, create one:<br />
# cd /etc/ssl/private/<br />
# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out server.key<br />
# chmod 400 server.key<br />
# openssl req -new -key server.key -out server.csr<br />
# openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
# chmod 444 server.crt<br />
<br />
=== Postfix ===<br />
Enable secure SMTP as described in [[Postfix#Secure SMTP]].<br />
<br />
To {{ic|/etc/postfix/main.cf}} append:<br />
relay_domains = *<br />
virtual_alias_maps = proxy:mysql:/etc/postfix/virtual_alias_maps.cf<br />
virtual_mailbox_domains = proxy:mysql:/etc/postfix/virtual_mailbox_domains.cf<br />
virtual_mailbox_maps = proxy:mysql:/etc/postfix/virtual_mailbox_maps.cf<br />
virtual_mailbox_base = /home/vmail<br />
virtual_mailbox_limit = 512000000<br />
virtual_minimum_uid = 5000<br />
virtual_transport = virtual<br />
virtual_uid_maps = static:5000<br />
virtual_gid_maps = static:5000<br />
local_transport = virtual<br />
local_recipient_maps = $virtual_mailbox_maps<br />
transport_maps = hash:/etc/postfix/transport<br />
<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_sasl_type = dovecot<br />
smtpd_sasl_path = /var/run/dovecot/auth-client<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_sasl_security_options = noanonymous<br />
smtpd_sasl_tls_security_options = $smtpd_sasl_security_options<br />
smtpd_tls_auth_only = yes<br />
smtpd_tls_cert_file = /etc/ssl/private/server.crt<br />
smtpd_tls_key_file = /etc/ssl/private/server.key<br />
smtpd_sasl_local_domain = $mydomain<br />
broken_sasl_auth_clients = yes<br />
smtpd_tls_loglevel = 1<br />
<br />
{{Warning|{{ic|<nowiki>relay_domains = *</nowiki>}} might be a bad idea (see http://www.postfix.org/BASIC_CONFIGURATION_README.html#relay_to). You usually do not want postfix to forward mail from strangers.}} <br />
<br />
{{ic|virtual_mailbox_domains}} is a list of the domains that you want to receive mail for. This CANNOT contain the domain that is set in {{ic|mydestination}}. That is why we left {{ic|mydestination}} to be localhost only.<br />
<br />
{{ic|virtual_mailbox_maps}} will contain the info about the virtual users and their mailbox locations. We are using a hash file to store the more permanent maps, and these will override the forwards in the MySQL database.<br />
<br />
{{ic|virtual_mailbox_base}} is the base directory where the virtual mailboxes will be stored.<br />
<br />
The gid and uid maps are the real system user account that the virtual mail will be owned by. This is for storage purposes. Since we will be using a web interface, and do not want people accessing this by any other means, we will be creating this account later with no login access.<br />
<br />
This references a lot of files that do not even exist yet. Create them with the following contents:<br />
<br />
{{hc|/etc/postfix/virtual_alias_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = domains<br />
select_field = virtual<br />
where_field = domain<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_domains.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = forwardings<br />
select_field = destination<br />
where_field = source<br />
</nowiki>}}<br />
<br />
{{hc|/etc/postfix/virtual_mailbox_maps.cf|<nowiki><br />
user = postfix_user<br />
password = hunter2<br />
hosts = localhost<br />
dbname = postfix_db<br />
table = users<br />
select_field = concat(domain,'/',email,'/')<br />
where_field = email<br />
</nowiki>}}<br />
<br />
{{Note|Instead of having a directory structure something like ''/home/vmail/example.com/user@example.com'' you can have cleaner subdirectories (without the additional domain name) by replacing ''select_field'' and ''where_field'' with:<br />
{{bc|1=query = SELECT CONCAT(SUBSTRING_INDEX(email,'@',-1),'/',SUBSTRING_INDEX(email,'@',1),'/') FROM users WHERE email='%s'}}<br />
}}<br />
<br />
Run ''postmap'' on ''transport'' to generate its db:<br />
# postmap /etc/postfix/transport<br />
<br />
=== Dovecot ===<br />
Start by creating a new {{ic|/etc/dovecot/dovecot.conf}} with the following contents:<br />
protocols = imap<br />
auth_mechanisms = plain<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
userdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
<br />
service auth {<br />
unix_listener auth-client {<br />
group = postfix<br />
mode = 0660<br />
user = postfix<br />
}<br />
user = root<br />
}<br />
<br />
mail_home = /home/vmail/%d/%u<br />
mail_location = maildir:~<br />
<br />
ssl_cert = </etc/ssl/private/server.crt<br />
ssl_key = </etc/ssl/private/server.key<br />
<br />
If you instead want to modify {{ic|dovecot.conf.sample}}, beware that the default configuration file imports the content of {{ic|conf.d/*.conf}}. Those files call other files that aren't present in our configuration.<br />
<br />
See http://wiki2.dovecot.org/Variables for the docevot variables %d and %u.<br />
<br />
Now obviously we also need the {{ic|/etc/dovecot/dovecot-sql.conf}} we just referenced in the config above. Go ahead and create a {{ic|/etc/dovecot/dovecot-sql.conf}} with these contents:<br />
driver = mysql<br />
connect = host=localhost dbname=postfix_db user=postfix_user password=hunter2<br />
# The new name for MD5 is MD5-CRYPT so you might need to change this depending on version<br />
default_pass_scheme = MD5-CRYPT<br />
# Get the mailbox<br />
user_query = SELECT '/home/vmail/%d/%u' as home, 'maildir:/home/vmail/%d/%u' as mail, 5000 AS uid, 5000 AS gid, concat('dirsize:storage=', quota) AS quota FROM mailbox WHERE username = '%u' AND active = '1'<br />
# Get the password<br />
password_query = SELECT username as user, password, '/home/vmail/%d/%u' as userdb_home, 'maildir:/home/vmail/%d/%u' as userdb_mail, 5000 as userdb_uid, 5000 as userdb_gid FROM mailbox WHERE username = '%u' AND active = '1'<br />
# If using client certificates for authentication, comment the above and uncomment the following<br />
#password_query = SELECT null AS password, ‘%u’ AS user<br />
<br />
=== PostfixAdmin ===<br />
See [[Postfix#PostfixAdmin]].<br />
<br />
=== Roundcube ===<br />
Roundcube needs a separate database to work. You'll need to provide information about the database during installation. Make sure that the {{ic|pdo_mysql.so}} extension is uncommented in your {{ic|php.ini}} file. Also check the {{ic|.htaccess}} for access restrictions. Assuming that localhost is your current host, navigate a browser to ''http://localhost/roundcube/installer/'' and follow the instructions. You should not use the same database for Roundcube that you already used for PostfixAdmin: create a second database "roundcube_db" and a "roundcube_user" for use with Roundcube. <br />
<br />
While running the installer, make sure to address the IMAP host with '''ssl://localhost/''' or '''tls://localhost/''' instead of just '''localhost'''. Use port 993. Likewise with SMTP, make sure to provide '''ssl://localhost/''' on port 465 if you used the wrapper mode and '''tls://localhost/''' on port 587 if you used the proper TLS mode. See [[#Postfix|here]] for an explanation on that.<br />
<br />
The post install process is similar to any other webapps like [[PhpMyAdmin]] or PostFixAdmin. The configuration file is {{ic|/etc/webapps/roundcubemail/config/config.inc.php}} which works as an override over {{ic|default.inc.php}}.<br />
<br />
If you are using Apache, copy the example configuration file to your webserver configuration directory.<br />
# cp /etc/webapps/roundcubemail/apache.conf /etc/httpd/conf/extra/httpd-roundcubemail.conf<br />
<br />
Add the include line in {{ic|/etc/httpd/conf/httpd.conf}}<br />
Include conf/extra/httpd-roundcubemail.conf<br />
To let users change their passwords from within Roundcube, do the following:<br />
<br />
Enable password plugin by adding this line to {{ic|/etc/webapps/roundcubemail/config/config.inc.php}}:<br />
$rcmail_config['plugins'] = array('password');<br />
<br />
Configure password plugin in {{ic|/usr/share/webapps/roundcubemail/plugins/password/config.inc.php}}:<br />
$config['password_driver'] = 'sql';<br />
$config['password_db_dsn'] = 'mysql://postfix_database_user:password@localhost/postfix_database_name';<br />
$config['password_query'] = 'UPDATE mailbox SET password=%c WHERE username=%u';<br />
<br />
== Fire it up ==<br />
Since now hopefully everything is set up correctly, all necessary daemons should be started for a test run:<br />
# systemctl start postfix dovecot<br />
<br />
Now for testing purposes, create a domain and mail account in PostfixAdmin. Try to login to this account using Roundcube. Now send yourself a mail.<br />
<br />
== Optional Items ==<br />
Although these items are not required, they definitely add more completeness to your setup<br />
<br />
=== Quota ===<br />
To enable mailbox quota support by dovecot, do the following: <br />
*First add the following lines to /etc/dovecot.conf<br />
dict {<br />
quotadict = mysql:/etc/dovecot/dovecot-dict-sql.conf.ext<br />
}<br />
service dict {<br />
unix_listener dict {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
user = root<br />
}<br />
service quota-warning {<br />
executable = script /usr/local/bin/quota-warning.sh<br />
user = vmail<br />
unix_listener quota-warning {<br />
group = vmail<br />
mode = 0660<br />
user = vmail<br />
}<br />
} <br />
mail_plugins=quota<br />
protocol pop3 {<br />
mail_plugins = quota<br />
pop3_client_workarounds = outlook-no-nuls oe-ns-eoh<br />
pop3_uidl_format = %08Xu%08Xv<br />
}<br />
protocol lda {<br />
mail_plugins = quota<br />
postmaster_address = postmaster@yourdomain.com<br />
}<br />
protocol imap {<br />
mail_plugins = $mail_plugins imap_quota<br />
mail_plugin_dir = /usr/lib/dovecot/modules<br />
}<br />
plugin {<br />
quota = dict:User quota::proxy::quotadict<br />
quota_rule2 = Trash:storage=+10%%<br />
quota_warning = storage=95%% quota-warning 95 %u<br />
quota_warning2 = storage=80%% quota-warning 80 %u<br />
quota_warning3 = -storage=100%% quota-warning below 100 %u # user is no longer over quota<br />
<br />
*Create a new file /etc/dovecot/dovecot-dict-sql.conf.ext with the following code:<br />
connect = host=localhost dbname=yourdb user=youruser password=yourpassword<br />
map {<br />
pattern = priv/quota/storage<br />
table = quota2<br />
username_field = username<br />
value_field = bytes<br />
}<br />
map {<br />
pattern = priv/quota/messages<br />
table = quota2<br />
username_field = username<br />
value_field = messages<br />
}<br />
*Create a warning script /usr/local/bin/quota-warning.sh and make sure it is executable.<br />
#!/bin/sh<br />
PERCENT=$1<br />
USER=$2<br />
cat << EOF | /usr/lib/dovecot/dovecot-lda -d $USER -o "plugin/quota=maildir:User quota:noenforcing"<br />
From: postmaster@yourdomain.com<br />
Subject: quota warning<br />
<br />
THIS MESSAGE IS AUTOMATICALLY GENERATED BY THE MAIL SYSTEM. DO NOT REPLY TO IT.<br />
<br />
Dear User,<br />
Your mailbox is now $PERCENT% full. Please remove some mails from the server.<br />
Regards,<br />
Postmaster<br />
EOF<br />
<br />
*Edit the user_query line and add iterat_query in dovecot-sql.conf as following:<br />
user_query = SELECT '/home/vmail/%d/%u' as home, 'maildir:/home/vmail/%d/%u' as mail, 5000 AS uid, 5000 AS gid, concat('*:bytes=', quota) AS quota_rule FROM mailbox WHERE username = '%u' AND active = '1'<br />
iterate_query = SELECT username AS user FROM mailbox<br />
*Set up LDA as described above under SpamAssassin. If you're not using SpamAssassin, the pipe should look like this in /etc/postfix/master.cf :<br />
dovecot unix - n n - - pipe<br />
flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient}<br />
As above activate it in Postfix main.cf<br />
virtual_transport = dovecot<br />
*You can set up quota per each mailbox in postfixadmin. Make sure the relevant lines in config.inc.php look like this:<br />
$CONF['quota'] = 'YES';<br />
$CONF['quota_multiplier'] = '1024000';<br />
<br />
Restart postfix and dovecot services. If things go well, you should be able to list all users' quota and usage by the this command:<br />
doveadm quota get -A<br />
You should be able to see the quota in roundcube too.<br />
<br />
== Troubleshooting ==<br />
If you get errors like your imap/pop3 client failing to receive mails, take a look into your /var/log/mail.log file.<br />
It turned out that the maildir /home/vmail/mail@domain.tld is just being created if there is at least one email waiting. Otherwise there wouldn't be any need for the directory.</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Ruby_on_Rails&diff=277990Ruby on Rails2013-10-07T19:31:49Z<p>Lfxgroove: Add note about nginx not being compiled with passenger in official repos anymore</p>
<hr />
<div>[[Category:Web Server]]<br />
[[zh-CN:Ruby on Rails]]<br />
[http://rubyonrails.org/ Ruby on Rails], often shortened to Rails or RoR, is an open source web application framework for the Ruby programming language. It is intended to be used with an Agile development methodology that is used by web developers for rapid development.<br />
<br />
This document describes how to set up the Ruby on Rails Framework on an Arch Linux system.<br />
<br />
Ruby on Rails requires [[Ruby]] to be installed, so read that article first for installation instructions.<br />
<br />
== Option A: Installation via RubyGems (Recommended) ==<br />
<br />
{{Box Note | If this command is run without being root (using sudo or otherwise), the gem will be installed into the home directory of the user.}}<br />
<br />
# gem install rails<br />
<br />
Building the documentation takes a while. If you want to skip it, append the parameters --no-ri --no-rdoc to the install command.<br />
# gem install rails --no-ri --no-rdoc<br />
<br />
=== Updating Gems ===<br />
<br />
gem is a package manager for Ruby modules, somewhat like pacman is to Arch Linux. To update your gems, simply run:<br />
# gem update<br />
<br />
== Option B: Installation via pacgem (Recommended) ==<br />
<br />
You can install Rails using {{AUR|pacgem}} from the [[AUR]]. Pacgem automatically creates PKGBUILDs and Arch packages for each of the gems. These packages will then be installed using pacman.<br />
<br />
# pacgem rails<br />
<br />
The gem packages can be updated with<br />
<br />
# pacgem -u<br />
<br />
== Option C: Installing via the AUR (Not recommended) ==<br />
<br />
{{Warning|This is not recommended, as this might not include the latest Rails version, and additional dependencies may be introduced that may require you to run {{Ic|gem install}} anyway.}}<br />
There is a {{AUR|rails}} package available in the [[AUR]].<br />
<br />
== Configuration ==<br />
<br />
Rails is bundled with a basic HTTP server called WeBrick. You can create a test application to test it. First, create an application with the rails command:<br />
<br />
$ rails new testapp_name<br />
<br />
{{Note|If you get an error like {{ic|Errno::ENOENT: No such file or directory (...) An error occurred while installing x, and Bundler cannot continue.}}, run {{ic|# rails new testapp_name}} once as root. If it has completed successfully, delete {{ic|testapp_name/}} and run {{ic|$ rails new testapp_name}} again as a regular user.}}<br />
{{Note|If you get an error message like this:<br />
{{ic|... FetchError: SSL_connect returned&#61;1 errno&#61; 0 state&#61;SSLv2/v3 read server hello A: sslv3 alert handshake<br />
failure (https://s3.amazonaws.com/ production.s3.rubygems.org/gems/rake-10.0.3.gem) }}<br />
install {{Pkg|nodejs}} and try again.}}<br />
<br />
This creates a new folder inside your current working directory. <br />
<br />
$ cd testapp_name<br />
<br />
Next start the web server. It listens on port 3000 by default:<br />
<br />
$ rails server<br />
<br />
Now visit the testapp_name website on your local machine by opening http://localhost:3000 in your browser<br />
{{Note|If Ruby complains about not being able to find a JavaScript runtime, install {{Pkg|nodejs}}.}}<br />
<br />
A test-page should shown greeting you "Welcome aboard".<br />
<br />
== Application servers ==<br />
<br />
While the default Ruby On Rails HTTP server (WeBrick) is convenient for basic development it is not recommended for production use. Generally, you should choose between installing the Phusion Passenger module for your webserver ([[Apache]] or [[Nginx]]), or use a dedicated application-server (such as Mongrel or Unicorn) combined with a separate web-server acting as a reverse proxy.<br />
<br />
=== Mongrel ===<br />
Mongrel is a drop-in replacement for WeBrick, that can be run in precisely the same way, but offers better performance.<br />
<br />
First install the Mongrel gem:<br />
# gem install mongrel<br />
<br />
Then start it using:<br />
# mongrel_rails start<br />
<br />
Alternatively, you can just run "ruby script/server" again, as it replaces WeBrick by default.<br />
<br />
=== Unicorn ===<br />
[http://unicorn.bogomips.org/ Unicorn] is loosely based on Mongrel, and is used by Github. It uses a different architecture that tries harder to find the best child for handling a request. [https://github.com/blog/517-unicorn Explanation of differences between Unicorn and Mongrel].<br />
<br />
Install the Unicorn gem:<br />
# gem install unicorn<br />
<br />
Then create a configuration file for your application in {{ic|/etc/unicorn/}}. For example; here is a configuration example (Based on [http://www.warden.pl/2011/01/07/running-redmine-under-unicorn-in-debian/]) for Redmine:<br />
<br />
{{hc|/etc/unicorn/redmine.ru|<nowiki><br />
working_directory "/srv/http/redmine"<br />
pid "/tmp/redmine.pid"<br />
<br />
preload_app true<br />
timeout 60<br />
worker_processes 4<br />
listen 4000<br />
stderr_path('/var/log/unicorn.log')<br />
<br />
GC.respond_to?(:copy_on_write_friendly=) and GC.copy_on_write_friendly = true<br />
<br />
after_fork do |server, worker|<br />
#start the worker on port 4000, 4001, 4002 etc...<br />
addr = "0.0.0.0:#{4000 + worker.nr}"<br />
# infinite tries to start the worker<br />
server.listen(addr, :tries => -1, :delay => -1, :backlog => 128)<br />
<br />
#Drop privileges if running as root<br />
worker.user('nobody', 'nobody') if Process.euid == 0<br />
end<br />
</nowiki>}}<br />
<br />
Start it using:<br />
# usr/bin/unicorn -D -E production -c /etc/unicorn/redmine.ru<br />
<br />
==== Systemd service ====<br />
Put the following contents in {{ic|/etc/systemd/system/unicorn.service}}:<br />
{{hc|/etc/systemd/system/unicorn.service|2=<br />
[Unit]<br />
Description=Unicorn application server<br />
After=network.target<br />
<br />
[Service]<br />
Type=forking<br />
User=redmine<br />
ExecStart=/usr/bin/unicorn -D -E production -c /etc/unicorn/redmine.ru<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
You can now easily start and stop unicorn using systemctl<br />
<br />
==== Nginx Configuration ====<br />
After setting up [[Nginx]], configure unicorn as an upstream server using something like this (Warning: this is a stripped example. It probably doesn't work without additional configuration):<br />
{{bc|1=<br />
http {<br />
upstream unicorn {<br />
server 127.0.0.1:4000 fail_timeout=0;<br />
server 127.0.0.1:4001 fail_timeout=0;<br />
server 127.0.0.1:4002 fail_timeout=0;<br />
server 127.0.0.1:4003 fail_timeout=0;<br />
}<br />
<br />
server {<br />
listen 80 default;<br />
server_name YOURHOSTNAMEHERE;<br />
<br />
location / {<br />
root /srv/http/redmine/public;<br />
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;<br />
proxy_set_header Host $http_host;<br />
proxy_redirect off;<br />
proxy_pass http://unicorn;<br />
}<br />
}<br />
}<br />
}}<br />
<br />
=== Apache/Nginx (using Phusion Passenger) ===<br />
<br />
[http://www.modrails.com/ Passenger] also known as {{ic|mod_rails}} is a module available for [[Nginx]] and [[Apache]], that greatly simplifies setting up a Rails server environment. Nginx does not support modules as Apache and has to be compiled with {{ic|mod_rails}} in order to support Passenger; let Passenger compile it for you. As for Apache, let Passenger set up the module for you.<br />
<br />
{{note|The current Nginx package in the official repositories actually is compiled with the Passenger module, so you can install it via pacman. The configuration files are stored in {{ic|/etc/nginx/conf/}}.}}<br />
{{note|As of 2013-10-07 this doesn't seem to be the casy any longer and you will have to follow the remaining steps here}}<br />
<br />
Start by installing the 'passenger' gem:<br />
# gem install passenger<br />
<br />
If you are aiming to use [[Apache]], run:<br />
# passenger-install-apache2-module<br />
<br />
In case a rails application is deployed with a sub-URI, like http://example.com/yourapplication, some additional configuration is required, see [http://www.modrails.com/documentation/Users%20guide%20Apache.html#deploying_rails_to_sub_uri the modrails documentation]<br />
<br />
For [[Nginx]]:<br />
# passenger-install-nginx-module<br />
<br />
The installer will provide you with any additional information regarding the installation (such as installing additional libraries).<br />
<br />
To serve an application with Nginx, configure it as follows:<br />
<pre><br />
server {<br />
server_name app.example.org;<br />
root path_to_app/public; # Be sure to point to 'public' folder!<br />
passenger_enabled on;<br />
rails_env development; # Rails environment.<br />
}<br />
</pre><br />
<br />
== Databases ==<br />
<br />
Most web applications will need to interact with some sort of database. ActiveRecord (the ORM used by Rails to provide database abstraction) supports several database vendors, the most popular of which are MySQL, SQLite, and PostgreSQL.<br />
<br />
=== SQLite ===<br />
<br />
SQLite is the default lightweight database for Ruby on Rails. To enable SQLite, simply install {{Pkg|sqlite3}}.<br />
<br />
=== PostgreSQL ===<br />
<br />
Install {{Pkg|postgresql}}.<br />
<br />
=== MySQL ===<br />
<br />
First, install and configure a MySQL server. Please refer to [[MySQL]] on how to do this.<br />
<br />
A gem with some native extensions is required, probably best installed as root:<br />
# gem install mysql<br />
<br />
You can generate a rails application configured for MySQL by using the {{ic|-d}} parameter:<br />
$ rails new testapp_name -d mysql<br />
<br />
You then need to edit {{ic|config/database.yml}}. Rails uses different databases for development, testing, production and other environments. Here is an example development configuration for MySQL running on localhost:<br />
<br />
development:<br />
adapter: mysql<br />
database: my_application_database<br />
username: development<br />
password: my_secret_password<br />
<br />
Note that you do not have to actually create the database using MySQL, as this can be done via Rails with:<br />
# rake db:create<br />
<br />
If no errors are shown, then your database has been created and Rails can talk to your MySQL database.<br />
<br />
== Option C: The Perfect Rails Setup ==<br />
<br />
''Phusion Passenger running multiple Ruby versions.''<br />
<br />
* [https://www.archlinux.org/ Archlinux]: A simple, lightweight distribution. ;)<br />
* [http://www.nginx.org/ Nginx]: A fast and lightweight '''web server''' with a strong focus on high concurrency, performance and low memory usage.<br />
* [http://www.modrails.com/ Passenger] (a.k.a. mod_rails or mod_rack): Supports both Apache and Nginx web servers. It makes deployment of Ruby web applications, such as those built on Ruby on Rails web framework, a breeze.<br />
* [http://www.rubyenterpriseedition.com/ Ruby Enterprise Edition] (REE): Passenger allows Ruby on Rails applications to use about 33% less memory, when used in combination with REE.<br />
* [https://rvm.io/ Ruby Version Manager] (RVM): A command-line tool which allows you to easily install, manage, and work with multiple Ruby environments from interpreters to sets of gems. RVM lets you deploy each project with its own completely self-contained and dedicated environment —from the specific version of ruby, all the way down to the precise set of required gems to run your application—.<br />
* [http://sqlite.org/ SQLite]: The default lightweight '''database''' for Ruby on Rails.<br />
<br />
=== Step 0: SQLite ===<br />
<br />
Install {{Pkg|sqlite}}.<br />
<br />
{{note|Of course SQLite is not critical in this setup, you can use MySQL and PostgreSQL as well.}}<br />
<br />
=== Step 1: RVM ===<br />
<br />
Make a multi-user [[RVM]] installation as specified [[RVM#Multi-user_installation|here]].<br />
<br />
In the 'adding users to the rvm group' step, do<br />
# usermod -a -G rvm http<br />
# usermod -a -G rvm nobody<br />
. http and nobody are the users related to Nginx and Passenger, respectively.<br />
<br />
{{note|Maybe adding the 'nobody' user to the 'rvm' group is not necessary.}}<br />
<br />
=== Step 2: Rubies ===<br />
<br />
Once you have a working RVM installation in your hands, it is time to install the Ruby Enterprise Edition interpreter<br />
{{Note|During the installation of Ruby Enterprise Edition patches will be applied. Consider installing '''base-devel''' beforehand.}}<br />
<br />
$ rvm install ree<br />
. Also take the chance to include other interpreters you want to use, like the last Ruby version<br />
$ rvm install 2.0.0<br />
<br />
==== Advice ====<br />
<br />
There is a documented [https://bugs.ruby-lang.org/issues/6383#note-1 bug] with older versions of Ruby (ie. the 1.8.7 version that REE uses) and the GCC versions 4.6 and up. If you get segmentation fault errors when trying to install gems such as Passenger, remove your install of REE and reinstall with the following:<br />
<br />
$ rvm remove ree<br />
$ CFLAGS="-O2 -fno-tree-dce -fno-optimize-sibling-calls" rvm install ree<br />
<br />
It is also possible to make it work with older versions of GCC, but that requires considerably more time.<br />
<br />
I have found useful to delete the 'global' gemsets of the environments that have web applications. Their gems were somehow interfering with Passenger. Do not do<br />
$ rvm ree do gemset delete global<br />
$ rvm 2.0.0 do gemset delete global<br />
now, but consider this later if you encounter complications.<br />
<br />
=== Step 3: Nginx with Passenger support ===<br />
<br />
Do not install Nginx via pacman. This web server does not support modules as Apache, so it must be compiled from source with the functionality of ''mod_rails'' (Passenger). Fortunately this is straightforward thanks to the passenger gem. Get it:<br />
$ rvm use ree<br />
$ gem install passenger<br />
. The gem will be put into the 'default' gemset. Now execute the following script:<br />
<br />
{{note|The current nginx package in the official repos actually was compiled with the passenger module. So you can install it via pacman and skip this step. The config files are stored in /etc/nginx/conf/. }}<br />
<br />
$ rvmsudo passenger-install-nginx-module<br />
. It will download the sources of Nginx, compile and install it for you. It will guide you through all the process. (The default location for Nginx is /opt/nginx.)<br />
<br />
{{note|If you encounter a compilation error regarding Boost threads, see [https://bbs.archlinux.org/viewtopic.php?id&#61;139164 this] article.}}<br />
<br />
After completion, the script will require you to add two lines into the 'http block' at {{ic|/opt/nginx/conf/nginx.conf}} that look like:<br />
http { <br />
...<br />
passenger_root /usr/local/rvm/gems/ree-1.8.7-2011.03/gems/passenger-3.0.9;<br />
passenger_ruby /usr/local/rvm/wrappers/ree-1.8.7-2011.03/ruby;<br />
...<br />
}<br />
<br />
If you installed [[Nginx]] from pacman the {{ic|passenger_root}} needs to be changed to:<br />
passenger_root /usr/lib/passenger/;<br />
{{warning|Do not set it to {{ic|/usr/lib/passenger/bin/passenger}} since this will result in [[Nginx]] segfaulting when checking the config}}<br />
<br />
For everything that is not Ruby, use [[Nginx]] as usual to serve static pages, PHP and Python. Check the wiki page for more information.<br />
<br />
To enable the Nnginx service by default at start-up just run:<br />
# systemctl enable nginx.service<br />
<br />
=== Step 4: Gemsets and Apps ===<br />
<br />
For each Rails application you should have a gemset. Suppose that you want to try [http://refinerycms.com RefineryCMS] against [http://www.browsercms.org BrowserCMS], two open-source Content Management Systems based on Rails. Then you should do:<br />
$ rvm use ree@refinery --create<br />
$ gem install rails -v 3.0.11<br />
$ gem install passenger<br />
$ gem install refinerycms refinerycms-i18n sqlite3<br />
Deploy a RefineryCMS instance called ''refineria'':<br />
$ cd /srv/http/<br />
$ rvmsudo refinerycms refineria<br />
Again:<br />
$ rvm use 2.0.0@browser --create<br />
$ gem install passenger<br />
$ gem install browsercms sqlite3<br />
Deploy a BrowserCMS instance called ''navegador'':<br />
$ cd /srv/http/<br />
$ rvmsudo browsercms demo navegador<br />
$ cd /srv/http/navegador<br />
$ rvmsudo rake db:install<br />
<br />
=== Passenger for Nginx and Passenger Standalone ===<br />
<br />
Observe that the passenger gem was installed three times and with different intentions; in the environments<br />
* ''ree'' => for Nginx,<br />
* ''ree@refinery'' => Standalone, and<br />
* ''2.0.0@browser'' => Standalone.<br />
<br />
The strategy is to combine Passenger for Nginx with Passenger Standalone. One must first identify the Ruby environment (interpreter plus gemset) that one uses the most; in this setup the REE interpreter and the default gemset were selected. One then proceeds with setting up Passenger for Nginx to use that environment (step 3).<br />
* Applications within the chosen environment can be served as in [[Ruby_on_Rails#Apache.2FNginx_.28using_Phusion_Passenger.29|Apache/Nginx (using Phusion Passenger)]], page up in this article.<br />
* All applications that are to use a different Ruby version and/or gemset can be served separately through Passenger Standalone and hook into the main web server via a reverse proxy configuration (step 6).<br />
<br />
=== Step 5: .rvmrc files and ownerships ===<br />
<br />
This step is crucial for the correct behaviour of the setup. RVM seeks for .rvmrc files when changing folders; if it finds one, it reads it. In these files normally one stores a line like<br />
rvm <ruby_version>@<gemset_name><br />
so the specified environment is set at the entrance of applications' root folder.<br />
<br />
Create /srv/http/refineria/.rvmrc doing<br />
# echo "rvm ree@refinery" > /srv/http/refineria/.rvmrc<br />
, and /srv/http/navegador/.rvmrc with<br />
# echo "rvm 2.0.0@browser" > /srv/http/navegador/.rvmrc<br />
You have to enter to both application root folders now, because every first time that RVM finds a .rvmrc it asks you if you trust the given file, consequently you must validate the two files you have just created.<br />
<br />
These files aid the programs involved to find the correct gems.<br />
<br />
Apart, if applications' files and folders are not owned by the right user you will face database write-access problems. The use of rvmsudo produces ''root''-owned archives when generated by Rails; in the other hand, ''nobody'' is the user for Passenger —if you have not changed it—: who will use and should posses them. Fix this doing<br />
# chown -R nobody.nobody /srv/http/refineria /srv/http/navegador<br />
<br />
=== Step 6: Reverse proxies ===<br />
<br />
You have to start the Passenger Standalone web servers for your applications. So, do<br />
$ cd /srv/http/refineria<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
and<br />
$ cd /srv/http/navegador<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
. The first time that you run a Passenger Standalone it will perform a minor installation.<br />
<br />
Note that you are using ''unix domain'' sockets instead of the commonly-used ''TCP'' sockets; it turns out that unix domain are significantly faster than TCP sockets.<br />
<br />
{{note|If you are experimenting trouble with unix sockets, changing to TCP should work:<br />
rvmsudo passenger start -a 127.0.0.1 -p 3000 -d<br />
}}<br />
<br />
==== Launch Passenger Standalone daemons at system start-up ====<br />
<br />
''Do you have a script? Please post it here.''<br />
<br />
The systemd script below was made for a Typo blog I host at /srv/http/typo. It's located at /etc/systemd/system/passenger_typo.service. I set the Environment= tags (see "man systemd.exec") from the output of "rvm env". The only exception was PATH=, which I had to combine from my regular PATH and the output of rvm env.<br />
<br />
Note: If you don't set the "WorkingDirectory=" variable to your application folder, passenger will fail to find your app and will subsequently shut itself down.<br />
<br />
<pre><br />
[Unit]<br />
Description=Passenger Standalone Script for Typo<br />
After=network.target<br />
<br />
[Service]<br />
Type=forking<br />
WorkingDirectory=/srv/http/typo<br />
PIDFile=/srv/http/typo/tmp/pids/passenger.pid<br />
<br />
Environment=PATH=/usr/local/rvm/gems/ruby-2.0.0-p0@typo/bin:/usr/local/rvm/gems/ruby-2.0.0-p0@global/bin:/usr/local/rvm/rubies/ruby-2.0.0-p0/bin:/usr/local/rvm/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/bin/core_perl<br />
Environment=rvm_env_string=ruby-2.0.0-p0@typo<br />
Environment=rvm_path=/usr/local/rvm<br />
Environment=rvm_ruby_string=ruby-2.0.0-p0<br />
Environment=rvm_gemset_name=typo<br />
Environment=RUBY_VERSION=ruby-2.0.0-p0<br />
Environment=GEM_HOME=/usr/local/rvm/gems/ruby-2.0.0-p0@typo<br />
Environment=GEM_PATH=/usr/local/rvm/gems/ruby-2.0.0-p0@typo:/usr/local/rvm/gems/ruby-2.0.0-p0@global<br />
Environment=MY_RUBY_HOME=/usr/local/rvm/rubies/ruby-2.0.0-p0<br />
Environment=IRBRC=/usr/local/rvm/rubies/ruby-2.0.0-p0/.irbrc<br />
<br />
ExecStart=/bin/bash -c "rvmsudo passenger start --socket /srv/http/typo/tmp/sockets/passenger.socket -d"<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</pre><br />
<br />
=== Step 7: Deployment ===<br />
<br />
== With subdomains ==<br />
<br />
Once again edit /opt/nginx/conf/nginx.conf to include some vital instructions:<br />
<br />
<pre><br />
## RefineryCMS ##<br />
<br />
server {<br />
server_name refinery.domain.com;<br />
root /srv/http/refineria/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/refineria/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
<br />
## BrowserCMS ##<br />
<br />
server {<br />
server_name browser.domain.com;<br />
root /srv/http/navegador/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/navegador/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
{{note|Or if using TCP sockets, configure the ''proxy_pass'' directive like<br />
<pre>proxy_pass http://127.0.0.1:3000;</pre><br />
}}<br />
<br />
== Without subdomains ==<br />
<br />
If you for some reason don't want to host each application on it's own subdomain but rather in a url like: {{ic|site.com/railsapp}} then you could do something like this in your config:<br />
<br />
<pre><br />
server {<br />
server_name site.com;<br />
#Base for the html files etc<br />
root /srv/http/;<br />
<br />
#First application you want hosted under domain site.com/railsapp<br />
location /railsapp {<br />
root /srv/http/railsapp/public;<br />
#you may need to change passenger_base_uri to be the uri you want to point at, ie:<br />
#passenger_base_uri /railsapp;<br />
#but probably only if you're using the other solution with passenger phusion<br />
proxy_pass http://unix:/srv/http/railsapp/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
<br />
#Second applicatino you want hosted under domain site.com/anotherapp<br />
location /anotherapp {<br />
root /srv/http/anotherapp/public;<br />
#same thing about the passenger_base_uri here, but with value /anotherapp instead<br />
proxy_pass http://unix:/srv/http/anotherapp/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
At this point you are in conditions to run Nginx with:<br />
<br />
# systemctl start nginx<br />
<br />
and to access both CMSs through ''refinery.domain.com'' and ''browser.domain.com''.<br />
<br />
=== References ===<br />
<br />
* http://beginrescueend.com/integration/passenger<br />
* http://blog.phusion.nl/2010/09/21/phusion-passenger-running-multiple-ruby-versions<br />
<br />
== See also ==<br />
<br />
* [[Ruby]]<br />
* [[Nginx]]<br />
* [[LAMP]]<br />
* [[MySQL]]<br />
<br />
== References ==<br />
<br />
* Ruby on Rails http://rubyonrails.org/download.<br />
* Mongrel http://mongrel.rubyforge.org.</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=SOHO_Postfix&diff=246912SOHO Postfix2013-02-09T16:59:21Z<p>Lfxgroove: /* Dovecot */ Added note about %u needed for it to work properly</p>
<hr />
<div>[[Category:Mail Server]]<br />
This tutorial will configure [http://www.postfix.org/ Postfix] using [http://www.mysql.com/ MySQL] as backend, [http://www.courier-mta.org/imap/ Courier-IMAP] or [http://www.dovecot.org/ Dovecot] for IMAP-SSL, [http://postfixadmin.sourceforge.net/ Postfix Admin] for virtual domains/users management, [http://spamassassin.apache.org/ Spamassassin] for spam filtering, and [http://www.squirrelmail.org/ SquirrelMail] for webmail. '''Mailing list and anti-virus are in the works.'''<br />
<br />
What this tutorial '''''doesn't''''' do is a thorough explanation of how everything works with each other. If you are the curious mind, check out the project's documentations. I also expect you already have a good working Apache and MySQL servers.<br />
<br />
==Required packages==<br />
* postfix<br />
* mysql ('''phpmyadmin''' is optional but recommended!)<br />
* courier-imap<br />
* dovecot<br />
* courier-authlib<br />
* apache<br />
* php<br />
* squirrelmail<br />
* spamassassin<br />
<br />
==Downloads==<br />
* Postfix Admin<br />
The latest stable release as of this writing is v2.1.0.<br />
<br />
==What is Postfix?==<br />
From Postfix.org...<br />
<pre><br />
What is Postfix? It is Wietse Venema's mailer that started life at IBM research as an<br />
alternative to the widely-used Sendmail program.<br />
<br />
Postfix attempts to be fast, easy to administer, and secure. The outside has a definite<br />
Sendmail-ish flavor, but the inside is completely different.<br />
</pre><br />
If you want to know how exactly Postfix works, check out [http://www.linuxjournal.com/article/9454 Anatomy of Postfix]!<br />
<br />
==Installation==<br />
===''Software installation''===<br />
Installs Arch packages with following.<br />
pacman -S php mysql apache postfix dovecot courier-imap courier-authlib squirrelmail spamassassin<br />
<br />
Note: postfixadmin can be found in AUR<br />
<br />
Download [http://postfixadmin.sourceforge.net/ Postfix Admin], extract into '''/home/httpd/html/''' and make a symlink.<br />
<br />
ln -s /home/httpd/html/postfixadmin-2.1.0 /home/httpd/html/postfixadmin<br />
<br />
(there's a new folder structure for apache in Arch: the default httpd folder for html documents is ''/srv/http'')--[[User:Mvinnicius|mvinnicius]] 08:38, 31 January 2011 (EST)<br />
<br />
(If you install from [[AUR]] postfixadmin can be found in '''/usr/share/webapps/postfixAdmin/''') -- [[User:Foppe|Foppe]] ([[User talk:Foppe|talk]])<br />
<br />
===''General configuration''===<br />
====Setup folder to store domain e-mails====<br />
All your domains emails will go under '''/home/vmail/'''.<br />
groupadd -g 5000 vmail<br />
useradd -u 5000 -g vmail -s /sbin/nologin -d /home/vmail -m vmail<br />
chmod 750 /home/vmail<br />
<br />
====SSL certs====<br />
Certificates generated here can be used by httpd, ftp or any other services supports SSL.<br />
cd /etc/ssl/certs<br />
openssl req -new -x509 -newkey rsa:1024 -days 365 -keyout server.key -out server.crt<br />
When asked about "Common Name", use your FQDN. i.e. http://linuxmonkey.net<br />
<br />
openssl rsa -in server.key -out server.key<br />
Above removes passphrase.<br />
<br />
chown nobody:nobody server.key<br />
chmod 600 server.key<br />
mv server.key /etc/ssl/private/<br />
Above are extra securities in case you actually wants to use SSL the ''real'' way.<br />
----<br />
=====Courier-IMAP=====<br />
Courier-IMAP's SSL cert is a little different.<br />
<br />
vi /etc/courier-imap/imapd.cnf<br />
Make it to suit your environment.<br />
<br />
/usr/sbin/mkimapdcert<br />
Will generate /usr/share/imapd.pem<br />
<br />
mv /usr/share/imapd.pem /etc/courier-imap/<br />
Move the newly generated Courier-IMAP SSL cert.<br />
<br />
====Webmail====<br />
=====SquirrelMail=====<br />
Make the folder.<br />
mkdir /var/lib/squirrelmail<br />
chown nobody:nobody /var/lib/squirrelmail<br />
<br />
Configure SquirrelMail on CLI.<br />
cd /home/httpd/html/squirrelmail/config - (is now /srv/http/squirrelmail/config), 04.12.2011 <br />
perl conf.pl<br />
<br />
=====RoundCube=====<br />
Yes, it works! Check it out [http://roundcube.net/ here]!<br />
<br />
<pre><br />
RoundCube Webmail is a browser-based multilingual IMAP client with an application-like user interface.<br />
It provides full functionality you expect from an e-mail client, including MIME support, address book,<br />
folder manipulation, message searching and spell checking. RoundCube Webmail is written in PHP and<br />
requires a MySQL or Postgres database. The user interface is fully skinnable using XHTML and CSS 2.<br />
</pre><br />
<br />
As for the configuration of RoundCube, note that I'm using PostfixAdmin 2.2.1.1, which can make the query quite different.<br />
For the configuration, you should look in the main.inc.php, and consider several options:<br />
<pre><br />
$rcmail_config['auto_create_user'] = TRUE;<br />
$rcmail_config['default_host'] = 'your.fdm';<br />
$rcmail_config['virtuser_query'] = 'SELECT username FROM postfix.mailbox WHERE username = "%u" or name = "%u"';<br />
$rcmail_config['smtp_server'] = 'mail.your.fdm';<br />
$rcmail_config['smtp_user'] = '%u';<br />
$rcmail_config['smtp_pass'] = '%p';<br />
$rcmail_config['smtp_helo_host'] = 'your.fdm';<br />
$rcmail_config['imap_root'] = 'INBOX'; // Important: Otherwise, folders like "Sent" and "Trash" will not be created<br />
$rcmail_config['create_default_folders'] = TRUE;<br />
$rcmail_config['enable_spellcheck'] = FALSE; // Communicates with Google - do we want this?<br />
</pre><br />
<br />
====Spamassassin====<br />
Go over '''/etc/mail/spamassassin/local.cf''' and configure it to your needs.<br />
<br />
Create Spamassassin user/group and folder.<br />
groupadd -g 5001 spamd<br />
useradd -u 5001 -g spamd -s /sbin/nologin -d /var/lib/spamassassin -m spamd<br />
chown spamd:spamd /var/lib/spamassassin<br />
<br />
Make sure '''/etc/conf.d/spamd''' look like following.<br />
SAHOME="/var/lib/spamassassin/"<br />
SPAMD_OPTS="--create-prefs --max-children 5 --username spamd --helper-home-dir ${SAHOME} -s ${SAHOME}spamd.log --pidfile /var/run/spamd.pid"<br />
<br />
To leave the service ready to run, let's update the spamassassin matching patterns.<br />
/usr/bin/vendor_perl/sa-update<br />
<br />
====Postfix Admin====<br />
<br />
----<br />
<br />
Obs1: There's a package in [https://aur.archlinux.org/packages.php?ID=28103 AUR]<br />
<br />
Obs2: The user/group in the recent apache pkg are http:http)<br />
<br />
Obs3: Check the instructions for the use of setup.php in the postfixadmin folder<br />
--[[User:Mvinnicius|mvinnicius]] 08:47, 31 January 2011 (EST)<br />
----<br />
<br />
Sets up correct permissions.<br />
chown -R nobody:nobody /home/httpd/html/postfixadmin-2.1.0/<br />
cd /home/httpd/html/postfixadmin/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/admin/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/images/<br />
chmod 640 *.png<br />
cd /home/httpd/html/postfixadmin/languages/<br />
chmod 640 *.lang<br />
cd /home/httpd/html/postfixadmin/templates/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/users/<br />
chmod 640 *.php<br />
<br />
Look at '''/home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT''' and modify the lines with password of your like. (''edited by silvernode'' NOTE: DATABASE_MYSQL.txt does not seem to exist in postfixadmin-2.3.2) <br />
INSERT INTO user (Host, User, Password) VALUES ('localhost','postfix',password(''''YOUR_NEW_PASSWD''''));<br />
(Line 28?)<br />
<br />
INSERT INTO user (Host, User, Password) VALUES ('localhost','postfixadmin',password(''''YOUR_NEW_PASSWD''''));<br />
(Line 31?)<br />
<br />
Load Postfix Admin MySQL database structure.<br />
/etc/rc.d/mysqld start<br />
mysql -u root -p < /home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT<br />
/etc/rc.d/mysqld stop<br />
<br />
(Remember to remove '''YOUR_NEW_PASSWD''' from '''/home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT'''!)<br />
<br />
Make Postfix Admin configuration file.<br />
cp /home/httpd/html/postfixadmin/config.inc.php.sample /home/httpd/html/postfixadmin/config.inc.php<br />
chmod 640 /home/httpd/html/postfixadmin/config.inc.php<br />
You may want to go over '''/home/httpd/html/postfixadmin/config.inc.php''' and configure it to suit you, but the following line needs to match what password you set above.<br />
$CONF['database_password'] = ''''YOUR_NEW_PASSWD'''';<br />
(Line 32?)<br />
Make sure it uses newer MySQL protocol<br />
$CONF['database_type'] = 'mysqli';<br />
(Line 29?)<br />
<br />
====Courier-IMAP and Courier-authlib====<br />
Courier-IMAP is a bit harder to configure and noticeably slower compared to Dovecot. However, if you prefer something tried-and-true, Courier-IMAP won't disappoint you.<br />
<br />
Make sure following files have following contents.<br />
* /etc/conf.d/courier-imap<br />
CI_DAEMONS="imapd-ssl"<br />
<br />
* /etc/authlib/authdaemonrc<br />
authmodulelist="authmysql"<br />
<br />
* /etc/authlib/authmysqlrc<br />
MYSQL_SERVER localhost<br />
MYSQL_USERNAME postfix<br />
MYSQL_PASSWORD '''YOUR_NEW_PASSWD'''<br />
MYSQL_SOCKET /tmp/mysql.sock<br />
MYSQL_PORT 3306<br />
MYSQL_OPT 0<br />
MYSQL_DATABASE postfix<br />
MYSQL_USER_TABLE mailbox<br />
MYSQL_CRYPT_PWFIELD password<br />
MYSQL_UID_FIELD 5000<br />
MYSQL_GID_FIELD 5000<br />
MYSQL_LOGIN_FIELD username<br />
MYSQL_HOME_FIELD "/home/vmail"<br />
MYSQL_MAILDIR_FIELD maildir<br />
MYSQL_QUOTA_FIELD quota<br />
<br />
* /etc/courier-imap/imapd-ssl<br />
IMAPDSSLSTART=YES<br />
TLS_PROTOCOL=SSL23<br />
TLS_CERTFILE=/etc/courier-imap/imapd.pem<br />
<br />
====Dovecot====<br />
<pre><br />
Dovecot is an open source IMAP and POP3 server for Linux/UNIX-like systems, written with security<br />
primarily in mind. Dovecot is an excellent choice for both small and large installations. It's fast,<br />
simple to set up, requires no special administration and it uses very little memory.<br />
</pre><br />
<br />
''At this time Dovecot is recommended as it is faster and newer than courier-imap, it is also much easier to setup''<br />
<br />
Make sure the following files with following contents.<br />
<br />
I strongly recommend go over all settings within this file, but I've listed what's required.<br />
* /etc/dovecot/dovecot.conf<br />
<br />
Obs: In the recent package, besides the dovecot.conf file, the configurations below are splitted in other files at /etc/dovecot/conf.d--[[User:Mvinnicius|mvinnicius]] 09:02, 31 January 2011 (EST)<br />
<br />
protocols = imap # since new version of dovecot, 'imaps' is not necessary <br />
ssl = yes # or can be ssl = required<br />
ssl_cert = </etc/ssl/certs/server.crt<br />
ssl_key = </etc/ssl/private/server.key<br />
first_valid_uid = 5000<br />
first_valid_gid = 5000<br />
auth_username_chars = abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@<br />
namespace {<br />
inbox = yes<br />
location = maildir:/home/vmail/%u/ #The %u is needed since this setting overrides all others, probably this isn't even needed if you have the mysql setup<br />
#see http://wiki.dovecot.org/MailLocation<br />
prefix = <br />
separator = /<br />
type = private<br />
}<br />
protocol imap {<br />
imap_client_workarounds = delay-newmail tb-extra-mailbox-sep<br />
}<br />
protocol lda {<br />
postmaster_address = admin@'''YOUR_DOMAIN.TLD'''<br />
hostname = '''YOUR_SERVER_NAME'''<br />
sendmail_path = /usr/sbin/sendmail<br />
}<br />
service auth {<br />
unix_listener /var/spool/postfix/private/auth {<br />
group = postfix<br />
mode = 0666<br />
user = postfix<br />
}<br />
unix_listener auth-userdb {<br />
group = vmail<br />
mode = 0600<br />
user = vmail<br />
}<br />
}<br />
userdb {<br />
args = /etc/dovecot/dovecot-sql.conf<br />
driver = sql<br />
}<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
<br />
<br />
* /etc/dovecot/dovecot-sql.conf<br />
driver = mysql #if you are using mysql, check the dovecot wiki for other options<br />
connect = host=localhost dbname=postfix user=postfix password='''YOUR_NEW_PASSWD'''<br />
default_pass_scheme = CRYPT<br />
password_query = SELECT password FROM mailbox WHERE username = '%u' AND active = '1'<br />
user_query = SELECT maildir AS mail, 5000 AS uid, 5000 AS gid, "/home/vmail" AS home FROM mailbox WHERE username = '%u' AND active = '1'<br />
<br />
====PHP====<br />
Edit '''/etc/php/php.ini''' and make the following changes.<br />
magic_quotes_gpc = On<br />
(Required for Postfix Admin)<br />
<br />
open_basedir = /home/:/tmp/:/usr/share/pear/:/var/lib/squirrelmail/<br />
(Required for SquirrelMail)<br />
<br />
====Postfix====<br />
I '''strongly''' recommend you go through all the lines in '''/etc/postfix/main.cf''' and configure it to your needs. Only followings are required for this setup!<br />
mydestination = localhost<br />
<br />
mynetworks_style = host<br />
<br />
relay_domains = $mydestination<br />
<br />
Add the following to end of '''/etc/postfix/main.cf'''.<br />
# Postfix with MySQL maps (Configure domain emails with Postfix Admin)<br />
#<br />
# Virtual Mailbox Domain Settings<br />
virtual_alias_maps = mysql:/etc/postfix/mysql_virtual_alias_maps.cf<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql_virtual_domains_maps.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql_virtual_mailbox_maps.cf<br />
virtual_mailbox_limit = 51200000<br />
virtual_minimum_uid = 5000<br />
virtual_uid_maps = static:5000<br />
virtual_gid_maps = static:5000<br />
virtual_mailbox_base = /home/vmail<br />
virtual_transport = virtual<br />
# Additional for quota support<br />
virtual_create_maildirsize = yes<br />
virtual_mailbox_extended = yes<br />
virtual_mailbox_limit_maps = mysql:/etc/postfix/mysql_virtual_mailbox_limit_maps.cf<br />
virtual_mailbox_limit_override = yes<br />
virtual_maildir_limit_message = Sorry, your maildir has overdrawn your diskspace quota, please free up some space and try again.<br />
virtual_overquota_bounce = yes<br />
(Above addition scrapped from [https://help.ubuntu.com/community/PostfixCompleteVirtualMailSystemHowto Ubuntu Wiki (Postfix Complete Virtual Mail System)] <=== '''NOT COMPLETE!''')<br />
<br />
Create the following Postfix maps with contents provided but change out the password.<br />
<pre><br />
In Postfix, lookup tables are called maps. Postfix uses maps not only to find out<br />
where to send mail, but also to impose restrictions on clients, senders, and recipients,<br />
and to check certain patterns in email content.<br />
</pre><br />
* /etc/postfix/mysql_virtual_alias_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = alias<br />
select_field = goto<br />
where_field = address<br />
* /etc/postfix/mysql_virtual_domains_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = domain<br />
select_field = domain<br />
where_field = domain<br />
#additional_conditions = and backupmx = '0' and active = '1'<br />
* /etc/postfix/mysql_virtual_mailbox_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = mailbox<br />
select_field = maildir<br />
where_field = username<br />
#additional_conditions = and active = '1'<br />
* /etc/postfix/mysql_virtual_mailbox_limit_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = mailbox<br />
select_field = quota<br />
where_field = username<br />
#additional_conditions = and active = '1'<br />
<br />
Set the proper permissions on those map files.<br />
chgrp postfix /etc/postfix/mysql_*.cf<br />
chmod 640 /etc/postfix/mysql_*.cf<br />
<br />
Make Postfix pipe mails through Spamassassin first.<br />
* /etc/postfix/master.cf<br />
smtp inet n - n - - smtpd -o content_filter=spamassassin<br />
spamassassin unix - n n - - pipe user=nobody argv=/usr/bin/vendor_perl/spamc -f -e /usr/sbin/sendmail -oi -f ${sender} ${recipient}<br />
<br />
====SMTP-AUTH====<br />
This is '''*OPTIONAL*'''! I do recommend you use your ISP's SMTP service to send your e-mails.<br />
<br />
Basic setup is using SMTPS (SSL; port 465) using SASL+PAM to authenticate with MySQL backend.<br />
<br />
Install some packages first.<br />
pacman -S cyrus-sasl cyrus-sasl-plugins pam_mysql<br />
<br />
Make the following modifications to specified files.<br />
<br />
* /etc/postfix/main.cf<br />
relay_domains = *<br />
<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_sasl_security_options = noanonymous<br />
smtpd_sasl_tls_security_options = $smtpd_sasl_security_options<br />
smtpd_tls_auth_only = yes<br />
smtpd_tls_cert_file = /etc/ssl/certs/server.crt<br />
smtpd_tls_key_file = /etc/ssl/private/server.key<br />
smtpd_sasl_local_domain = $mydomain<br />
broken_sasl_auth_clients = yes<br />
smtpd_tls_loglevel = 1<br />
<br />
* /etc/postfix/master.cf<br />
smtps inet n - n - - smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes<br />
<br />
Note: as it turns out, '''smtps''' was never actually a valid entry in '''/etc/services''' (except briefly, for a few months in 1996... see https://bugs.archlinux.org/task/20436). Since recent versions of /etc/services are now "fixed", postfix will not be able to translate the string "smtps" into port 465 any more. As a workaround, you can do this:<br />
<br />
'''465''' inet n - n - - smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes<br />
<br />
(You can also change /etc/services so that 465/tcp is smtps again, but this will break mysteriously unless you also tell pacman not to ever touch that file, which, if you ever migrate your server or help a friend set up his, is something you're definitely going to forget you did... and then it will break mysteriously again and you'll spend a few hours Googling until you land here.)<br />
<br />
* /etc/pam.d/smtp<br />
auth required /usr/lib/security/pam_mysql.so user=postfix passwd='''YOUR_NEW_PASSWD''' host=localhost db=postfix table=mailbox usercolumn=username passwdcolumn=password crypt=1<br />
account sufficient /usr/lib/security/pam_mysql.so user=postfix passwd='''YOUR_NEW_PASSWD''' host=localhost db=postfix table=mailbox usercolumn=username passwdcolumn=password crypt=1<br />
<br />
''pam_mysql.so'' may also be located in ''/lib/security/'' instead of ''/usr/lib/security/''. I find Arch64 uses ''/usr/lib/security/pam_mysql.so'' and Arch32 uses ''/lib/security/pam_mysql.so''.<br />
<br />
* /etc/conf.d/saslauthd<br />
SASLAUTHD_OPTS="-m /var/run/saslauthd -r -a pam"<br />
<br />
* /usr/lib/sasl2/smtpd.conf<br />
pwcheck_method: saslauthd<br />
mech_list: plain login<br />
saslauthd_path: /var/run/saslauthd/mux<br />
log_level: 7<br />
<br />
==Put into production!==<br />
===Firing up services!===<br />
Run following command to start all services!<br />
for v in spamd mysqld httpd postfix dovecot;do /etc/rc.d/$v start ;done<br />
('''saslauthd''' if you plan to use SMTP-AUTH)<br />
<br />
If you plan to use Courier-IMAP, run following instead!<br />
for v in saslauthd spamd mysqld httpd postfix authdaemond courier-imap;do /etc/rc.d/$v start ;done<br />
('''saslauthd''' if you plan to use SMTP-AUTH)<br />
<br />
Go to following site to configure more stuff!<br />
* Postfix Admin<br />
http://YOUR_DOMAIN.TLD/postfixadmin/admin/<br />
(Default is '''USER''': admin '''PASS''': admin)<br />
I would look into Apache's documentation on .htaccess/.htpasswd and change out Postfix Admin's default admin page password.<br />
<br />
===Verify working===<br />
* Postfix<br />
Let's test see if Postfix is up and accepting connections.<br />
[root@monkey1 /etc/rc.d]# '''telnet localhost 25'''<br />
Trying 127.0.0.1...<br />
Connected to localhost.<br />
Escape character is '^]'.<br />
220 mail.YOUR_DOMAIN.TLD ESMTP Postfix (Arch Linux)<br />
'''ehlo YOUR_DOMAIN.TLD'''<br />
250-mail.YOUR_DOMAIN.TLD<br />
250-PIPELINING<br />
250-SIZE 10240000<br />
250-VRFY<br />
250-ETRN<br />
250-ENHANCEDSTATUSCODES<br />
250-8BITMIME<br />
250 DSN<br />
'''mail from: root@localhost'''<br />
250 2.1.0 Ok<br />
'''rcpt to: test@YOUR_DOMAIN.TLD'''<br />
250 2.1.5 Ok<br />
'''data'''<br />
354 End data with <CR><LF>.<CR><LF><br />
'''This is a test sending from root@localhost!'''<br />
'''.'''<br />
250 2.0.0 Ok: queued as 883E910C47B<br />
'''quit'''<br />
221 2.0.0 Bye<br />
Connection closed by foreign host.<br />
<br />
^^^^^^^^^^<br />
<br />
S-W-E-E-T! :)<br />
<br />
* Dovecot or Courier-IMAP<br />
Fire up your favorite mail client, that supports IMAP-SSL, and connect to your domain see if it works!<br />
<br />
* Spamassassin<br />
If you see something similar in your e-mail headers, Spamassassin is working!<br />
X-Spam-Checker-Version: SpamAssassin 3.2.3 (2007-08-08) on YOUR_DOMAIN.TLD<br />
X-Spam-Status: No, score=-0.2 required=3.0 tests=ALL_TRUSTED,MISSING_SUBJECT autolearn=no version=3.2.3<br />
<br />
* Postfix Admin<br />
Play around see everything works like it should.<br />
http://YOUR_DOMAIN.TLD/postfixadmin/<br />
<br />
* SquirrelMail<br />
http://YOUR_DOMAIN.TLD/squirrelmail/<br />
<br />
===Post-installation===<br />
If you firewalled your server, make sure the ports '''25 80 443 993''' (and '''465''' for SMTP-AUTH) are open!<br />
<br />
Don't forget to add services to your '''/etc/rc.conf'''!<br />
<br />
Any configuration files with '''YOUR_NEW_PASSWD''' in it you should '''''chmod 640''''' it!<br />
<br />
==Notes==<br />
Comments? Questions? Rants? Please let me know at '''''terii [-AT-] linuxmonkey [-DOT-] net'''''.<br />
<br />
You can also catch me on Freenode IRC under #archlinux; '''quad3d''', '''quad3datwork''', '''limlappy''', '''gangsterlicious''', or '''portofu'''.<br />
<br />
Thanks to [http://www.slicehost.com/ slicehost.com] for hosting my VPS! This guide is not possible without my VPS. Find this guide useful? Thinking about having your own VPS at slicehost.com? Ask me for my reference e-mail so I can get some credit! :)<br />
<br />
==See also==<br />
*[[Simple Virtual User Mail System]]<br />
*[[Courier MTA]]<br />
*[[Postfix]]</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=SOHO_Postfix&diff=246910SOHO Postfix2013-02-09T15:45:06Z<p>Lfxgroove: /* Dovecot */ Added small change to make authentication work properly, also added mysql parameter to the dovecot-sql.conf</p>
<hr />
<div>[[Category:Mail Server]]<br />
This tutorial will configure [http://www.postfix.org/ Postfix] using [http://www.mysql.com/ MySQL] as backend, [http://www.courier-mta.org/imap/ Courier-IMAP] or [http://www.dovecot.org/ Dovecot] for IMAP-SSL, [http://postfixadmin.sourceforge.net/ Postfix Admin] for virtual domains/users management, [http://spamassassin.apache.org/ Spamassassin] for spam filtering, and [http://www.squirrelmail.org/ SquirrelMail] for webmail. '''Mailing list and anti-virus are in the works.'''<br />
<br />
What this tutorial '''''doesn't''''' do is a thorough explanation of how everything works with each other. If you are the curious mind, check out the project's documentations. I also expect you already have a good working Apache and MySQL servers.<br />
<br />
==Required packages==<br />
* postfix<br />
* mysql ('''phpmyadmin''' is optional but recommended!)<br />
* courier-imap<br />
* dovecot<br />
* courier-authlib<br />
* apache<br />
* php<br />
* squirrelmail<br />
* spamassassin<br />
<br />
==Downloads==<br />
* Postfix Admin<br />
The latest stable release as of this writing is v2.1.0.<br />
<br />
==What is Postfix?==<br />
From Postfix.org...<br />
<pre><br />
What is Postfix? It is Wietse Venema's mailer that started life at IBM research as an<br />
alternative to the widely-used Sendmail program.<br />
<br />
Postfix attempts to be fast, easy to administer, and secure. The outside has a definite<br />
Sendmail-ish flavor, but the inside is completely different.<br />
</pre><br />
If you want to know how exactly Postfix works, check out [http://www.linuxjournal.com/article/9454 Anatomy of Postfix]!<br />
<br />
==Installation==<br />
===''Software installation''===<br />
Installs Arch packages with following.<br />
pacman -S php mysql apache postfix dovecot courier-imap courier-authlib squirrelmail spamassassin<br />
<br />
Note: postfixadmin can be found in AUR<br />
<br />
Download [http://postfixadmin.sourceforge.net/ Postfix Admin], extract into '''/home/httpd/html/''' and make a symlink.<br />
<br />
ln -s /home/httpd/html/postfixadmin-2.1.0 /home/httpd/html/postfixadmin<br />
<br />
(there's a new folder structure for apache in Arch: the default httpd folder for html documents is ''/srv/http'')--[[User:Mvinnicius|mvinnicius]] 08:38, 31 January 2011 (EST)<br />
<br />
(If you install from [[AUR]] postfixadmin can be found in '''/usr/share/webapps/postfixAdmin/''') -- [[User:Foppe|Foppe]] ([[User talk:Foppe|talk]])<br />
<br />
===''General configuration''===<br />
====Setup folder to store domain e-mails====<br />
All your domains emails will go under '''/home/vmail/'''.<br />
groupadd -g 5000 vmail<br />
useradd -u 5000 -g vmail -s /sbin/nologin -d /home/vmail -m vmail<br />
chmod 750 /home/vmail<br />
<br />
====SSL certs====<br />
Certificates generated here can be used by httpd, ftp or any other services supports SSL.<br />
cd /etc/ssl/certs<br />
openssl req -new -x509 -newkey rsa:1024 -days 365 -keyout server.key -out server.crt<br />
When asked about "Common Name", use your FQDN. i.e. http://linuxmonkey.net<br />
<br />
openssl rsa -in server.key -out server.key<br />
Above removes passphrase.<br />
<br />
chown nobody:nobody server.key<br />
chmod 600 server.key<br />
mv server.key /etc/ssl/private/<br />
Above are extra securities in case you actually wants to use SSL the ''real'' way.<br />
----<br />
=====Courier-IMAP=====<br />
Courier-IMAP's SSL cert is a little different.<br />
<br />
vi /etc/courier-imap/imapd.cnf<br />
Make it to suit your environment.<br />
<br />
/usr/sbin/mkimapdcert<br />
Will generate /usr/share/imapd.pem<br />
<br />
mv /usr/share/imapd.pem /etc/courier-imap/<br />
Move the newly generated Courier-IMAP SSL cert.<br />
<br />
====Webmail====<br />
=====SquirrelMail=====<br />
Make the folder.<br />
mkdir /var/lib/squirrelmail<br />
chown nobody:nobody /var/lib/squirrelmail<br />
<br />
Configure SquirrelMail on CLI.<br />
cd /home/httpd/html/squirrelmail/config - (is now /srv/http/squirrelmail/config), 04.12.2011 <br />
perl conf.pl<br />
<br />
=====RoundCube=====<br />
Yes, it works! Check it out [http://roundcube.net/ here]!<br />
<br />
<pre><br />
RoundCube Webmail is a browser-based multilingual IMAP client with an application-like user interface.<br />
It provides full functionality you expect from an e-mail client, including MIME support, address book,<br />
folder manipulation, message searching and spell checking. RoundCube Webmail is written in PHP and<br />
requires a MySQL or Postgres database. The user interface is fully skinnable using XHTML and CSS 2.<br />
</pre><br />
<br />
As for the configuration of RoundCube, note that I'm using PostfixAdmin 2.2.1.1, which can make the query quite different.<br />
For the configuration, you should look in the main.inc.php, and consider several options:<br />
<pre><br />
$rcmail_config['auto_create_user'] = TRUE;<br />
$rcmail_config['default_host'] = 'your.fdm';<br />
$rcmail_config['virtuser_query'] = 'SELECT username FROM postfix.mailbox WHERE username = "%u" or name = "%u"';<br />
$rcmail_config['smtp_server'] = 'mail.your.fdm';<br />
$rcmail_config['smtp_user'] = '%u';<br />
$rcmail_config['smtp_pass'] = '%p';<br />
$rcmail_config['smtp_helo_host'] = 'your.fdm';<br />
$rcmail_config['imap_root'] = 'INBOX'; // Important: Otherwise, folders like "Sent" and "Trash" will not be created<br />
$rcmail_config['create_default_folders'] = TRUE;<br />
$rcmail_config['enable_spellcheck'] = FALSE; // Communicates with Google - do we want this?<br />
</pre><br />
<br />
====Spamassassin====<br />
Go over '''/etc/mail/spamassassin/local.cf''' and configure it to your needs.<br />
<br />
Create Spamassassin user/group and folder.<br />
groupadd -g 5001 spamd<br />
useradd -u 5001 -g spamd -s /sbin/nologin -d /var/lib/spamassassin -m spamd<br />
chown spamd:spamd /var/lib/spamassassin<br />
<br />
Make sure '''/etc/conf.d/spamd''' look like following.<br />
SAHOME="/var/lib/spamassassin/"<br />
SPAMD_OPTS="--create-prefs --max-children 5 --username spamd --helper-home-dir ${SAHOME} -s ${SAHOME}spamd.log --pidfile /var/run/spamd.pid"<br />
<br />
To leave the service ready to run, let's update the spamassassin matching patterns.<br />
/usr/bin/vendor_perl/sa-update<br />
<br />
====Postfix Admin====<br />
<br />
----<br />
<br />
Obs1: There's a package in [https://aur.archlinux.org/packages.php?ID=28103 AUR]<br />
<br />
Obs2: The user/group in the recent apache pkg are http:http)<br />
<br />
Obs3: Check the instructions for the use of setup.php in the postfixadmin folder<br />
--[[User:Mvinnicius|mvinnicius]] 08:47, 31 January 2011 (EST)<br />
----<br />
<br />
Sets up correct permissions.<br />
chown -R nobody:nobody /home/httpd/html/postfixadmin-2.1.0/<br />
cd /home/httpd/html/postfixadmin/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/admin/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/images/<br />
chmod 640 *.png<br />
cd /home/httpd/html/postfixadmin/languages/<br />
chmod 640 *.lang<br />
cd /home/httpd/html/postfixadmin/templates/<br />
chmod 640 *.php<br />
cd /home/httpd/html/postfixadmin/users/<br />
chmod 640 *.php<br />
<br />
Look at '''/home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT''' and modify the lines with password of your like. (''edited by silvernode'' NOTE: DATABASE_MYSQL.txt does not seem to exist in postfixadmin-2.3.2) <br />
INSERT INTO user (Host, User, Password) VALUES ('localhost','postfix',password(''''YOUR_NEW_PASSWD''''));<br />
(Line 28?)<br />
<br />
INSERT INTO user (Host, User, Password) VALUES ('localhost','postfixadmin',password(''''YOUR_NEW_PASSWD''''));<br />
(Line 31?)<br />
<br />
Load Postfix Admin MySQL database structure.<br />
/etc/rc.d/mysqld start<br />
mysql -u root -p < /home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT<br />
/etc/rc.d/mysqld stop<br />
<br />
(Remember to remove '''YOUR_NEW_PASSWD''' from '''/home/httpd/html/postfixadmin/DATABASE_MYSQL.TXT'''!)<br />
<br />
Make Postfix Admin configuration file.<br />
cp /home/httpd/html/postfixadmin/config.inc.php.sample /home/httpd/html/postfixadmin/config.inc.php<br />
chmod 640 /home/httpd/html/postfixadmin/config.inc.php<br />
You may want to go over '''/home/httpd/html/postfixadmin/config.inc.php''' and configure it to suit you, but the following line needs to match what password you set above.<br />
$CONF['database_password'] = ''''YOUR_NEW_PASSWD'''';<br />
(Line 32?)<br />
Make sure it uses newer MySQL protocol<br />
$CONF['database_type'] = 'mysqli';<br />
(Line 29?)<br />
<br />
====Courier-IMAP and Courier-authlib====<br />
Courier-IMAP is a bit harder to configure and noticeably slower compared to Dovecot. However, if you prefer something tried-and-true, Courier-IMAP won't disappoint you.<br />
<br />
Make sure following files have following contents.<br />
* /etc/conf.d/courier-imap<br />
CI_DAEMONS="imapd-ssl"<br />
<br />
* /etc/authlib/authdaemonrc<br />
authmodulelist="authmysql"<br />
<br />
* /etc/authlib/authmysqlrc<br />
MYSQL_SERVER localhost<br />
MYSQL_USERNAME postfix<br />
MYSQL_PASSWORD '''YOUR_NEW_PASSWD'''<br />
MYSQL_SOCKET /tmp/mysql.sock<br />
MYSQL_PORT 3306<br />
MYSQL_OPT 0<br />
MYSQL_DATABASE postfix<br />
MYSQL_USER_TABLE mailbox<br />
MYSQL_CRYPT_PWFIELD password<br />
MYSQL_UID_FIELD 5000<br />
MYSQL_GID_FIELD 5000<br />
MYSQL_LOGIN_FIELD username<br />
MYSQL_HOME_FIELD "/home/vmail"<br />
MYSQL_MAILDIR_FIELD maildir<br />
MYSQL_QUOTA_FIELD quota<br />
<br />
* /etc/courier-imap/imapd-ssl<br />
IMAPDSSLSTART=YES<br />
TLS_PROTOCOL=SSL23<br />
TLS_CERTFILE=/etc/courier-imap/imapd.pem<br />
<br />
====Dovecot====<br />
<pre><br />
Dovecot is an open source IMAP and POP3 server for Linux/UNIX-like systems, written with security<br />
primarily in mind. Dovecot is an excellent choice for both small and large installations. It's fast,<br />
simple to set up, requires no special administration and it uses very little memory.<br />
</pre><br />
<br />
''At this time Dovecot is recommended as it is faster and newer than courier-imap, it is also much easier to setup''<br />
<br />
Make sure the following files with following contents.<br />
<br />
I strongly recommend go over all settings within this file, but I've listed what's required.<br />
* /etc/dovecot/dovecot.conf<br />
<br />
Obs: In the recent package, besides the dovecot.conf file, the configurations below are splitted in other files at /etc/dovecot/conf.d--[[User:Mvinnicius|mvinnicius]] 09:02, 31 January 2011 (EST)<br />
<br />
protocols = imap # since new version of dovecot, 'imaps' is not necessary <br />
ssl = yes # or can be ssl = required<br />
ssl_cert = </etc/ssl/certs/server.crt<br />
ssl_key = </etc/ssl/private/server.key<br />
first_valid_uid = 5000<br />
first_valid_gid = 5000<br />
auth_username_chars = abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@<br />
namespace {<br />
inbox = yes<br />
location = maildir:/home/vmail/<br />
prefix = <br />
separator = /<br />
type = private<br />
}<br />
protocol imap {<br />
imap_client_workarounds = delay-newmail tb-extra-mailbox-sep<br />
}<br />
protocol lda {<br />
postmaster_address = admin@'''YOUR_DOMAIN.TLD'''<br />
hostname = '''YOUR_SERVER_NAME'''<br />
sendmail_path = /usr/sbin/sendmail<br />
}<br />
service auth {<br />
unix_listener /var/spool/postfix/private/auth {<br />
group = postfix<br />
mode = 0666<br />
user = postfix<br />
}<br />
unix_listener auth-userdb {<br />
group = vmail<br />
mode = 0600<br />
user = vmail<br />
}<br />
}<br />
userdb {<br />
args = /etc/dovecot/dovecot-sql.conf<br />
driver = sql<br />
}<br />
passdb {<br />
driver = sql<br />
args = /etc/dovecot/dovecot-sql.conf<br />
}<br />
<br />
<br />
* /etc/dovecot/dovecot-sql.conf<br />
driver = mysql #if you are using mysql, check the dovecot wiki for other options<br />
connect = host=localhost dbname=postfix user=postfix password='''YOUR_NEW_PASSWD'''<br />
default_pass_scheme = CRYPT<br />
password_query = SELECT password FROM mailbox WHERE username = '%u' AND active = '1'<br />
user_query = SELECT maildir AS mail, 5000 AS uid, 5000 AS gid, "/home/vmail" AS home FROM mailbox WHERE username = '%u' AND active = '1'<br />
<br />
====PHP====<br />
Edit '''/etc/php/php.ini''' and make the following changes.<br />
magic_quotes_gpc = On<br />
(Required for Postfix Admin)<br />
<br />
open_basedir = /home/:/tmp/:/usr/share/pear/:/var/lib/squirrelmail/<br />
(Required for SquirrelMail)<br />
<br />
====Postfix====<br />
I '''strongly''' recommend you go through all the lines in '''/etc/postfix/main.cf''' and configure it to your needs. Only followings are required for this setup!<br />
mydestination = localhost<br />
<br />
mynetworks_style = host<br />
<br />
relay_domains = $mydestination<br />
<br />
Add the following to end of '''/etc/postfix/main.cf'''.<br />
# Postfix with MySQL maps (Configure domain emails with Postfix Admin)<br />
#<br />
# Virtual Mailbox Domain Settings<br />
virtual_alias_maps = mysql:/etc/postfix/mysql_virtual_alias_maps.cf<br />
virtual_mailbox_domains = mysql:/etc/postfix/mysql_virtual_domains_maps.cf<br />
virtual_mailbox_maps = mysql:/etc/postfix/mysql_virtual_mailbox_maps.cf<br />
virtual_mailbox_limit = 51200000<br />
virtual_minimum_uid = 5000<br />
virtual_uid_maps = static:5000<br />
virtual_gid_maps = static:5000<br />
virtual_mailbox_base = /home/vmail<br />
virtual_transport = virtual<br />
# Additional for quota support<br />
virtual_create_maildirsize = yes<br />
virtual_mailbox_extended = yes<br />
virtual_mailbox_limit_maps = mysql:/etc/postfix/mysql_virtual_mailbox_limit_maps.cf<br />
virtual_mailbox_limit_override = yes<br />
virtual_maildir_limit_message = Sorry, your maildir has overdrawn your diskspace quota, please free up some space and try again.<br />
virtual_overquota_bounce = yes<br />
(Above addition scrapped from [https://help.ubuntu.com/community/PostfixCompleteVirtualMailSystemHowto Ubuntu Wiki (Postfix Complete Virtual Mail System)] <=== '''NOT COMPLETE!''')<br />
<br />
Create the following Postfix maps with contents provided but change out the password.<br />
<pre><br />
In Postfix, lookup tables are called maps. Postfix uses maps not only to find out<br />
where to send mail, but also to impose restrictions on clients, senders, and recipients,<br />
and to check certain patterns in email content.<br />
</pre><br />
* /etc/postfix/mysql_virtual_alias_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = alias<br />
select_field = goto<br />
where_field = address<br />
* /etc/postfix/mysql_virtual_domains_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = domain<br />
select_field = domain<br />
where_field = domain<br />
#additional_conditions = and backupmx = '0' and active = '1'<br />
* /etc/postfix/mysql_virtual_mailbox_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = mailbox<br />
select_field = maildir<br />
where_field = username<br />
#additional_conditions = and active = '1'<br />
* /etc/postfix/mysql_virtual_mailbox_limit_maps.cf<br />
user = postfix<br />
password = '''YOUR_NEW_PASSWD'''<br />
hosts = localhost<br />
dbname = postfix<br />
table = mailbox<br />
select_field = quota<br />
where_field = username<br />
#additional_conditions = and active = '1'<br />
<br />
Set the proper permissions on those map files.<br />
chgrp postfix /etc/postfix/mysql_*.cf<br />
chmod 640 /etc/postfix/mysql_*.cf<br />
<br />
Make Postfix pipe mails through Spamassassin first.<br />
* /etc/postfix/master.cf<br />
smtp inet n - n - - smtpd -o content_filter=spamassassin<br />
spamassassin unix - n n - - pipe user=nobody argv=/usr/bin/vendor_perl/spamc -f -e /usr/sbin/sendmail -oi -f ${sender} ${recipient}<br />
<br />
====SMTP-AUTH====<br />
This is '''*OPTIONAL*'''! I do recommend you use your ISP's SMTP service to send your e-mails.<br />
<br />
Basic setup is using SMTPS (SSL; port 465) using SASL+PAM to authenticate with MySQL backend.<br />
<br />
Install some packages first.<br />
pacman -S cyrus-sasl cyrus-sasl-plugins pam_mysql<br />
<br />
Make the following modifications to specified files.<br />
<br />
* /etc/postfix/main.cf<br />
relay_domains = *<br />
<br />
smtpd_sasl_auth_enable = yes<br />
smtpd_recipient_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination<br />
smtpd_sasl_security_options = noanonymous<br />
smtpd_sasl_tls_security_options = $smtpd_sasl_security_options<br />
smtpd_tls_auth_only = yes<br />
smtpd_tls_cert_file = /etc/ssl/certs/server.crt<br />
smtpd_tls_key_file = /etc/ssl/private/server.key<br />
smtpd_sasl_local_domain = $mydomain<br />
broken_sasl_auth_clients = yes<br />
smtpd_tls_loglevel = 1<br />
<br />
* /etc/postfix/master.cf<br />
smtps inet n - n - - smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes<br />
<br />
Note: as it turns out, '''smtps''' was never actually a valid entry in '''/etc/services''' (except briefly, for a few months in 1996... see https://bugs.archlinux.org/task/20436). Since recent versions of /etc/services are now "fixed", postfix will not be able to translate the string "smtps" into port 465 any more. As a workaround, you can do this:<br />
<br />
'''465''' inet n - n - - smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes<br />
<br />
(You can also change /etc/services so that 465/tcp is smtps again, but this will break mysteriously unless you also tell pacman not to ever touch that file, which, if you ever migrate your server or help a friend set up his, is something you're definitely going to forget you did... and then it will break mysteriously again and you'll spend a few hours Googling until you land here.)<br />
<br />
* /etc/pam.d/smtp<br />
auth required /usr/lib/security/pam_mysql.so user=postfix passwd='''YOUR_NEW_PASSWD''' host=localhost db=postfix table=mailbox usercolumn=username passwdcolumn=password crypt=1<br />
account sufficient /usr/lib/security/pam_mysql.so user=postfix passwd='''YOUR_NEW_PASSWD''' host=localhost db=postfix table=mailbox usercolumn=username passwdcolumn=password crypt=1<br />
<br />
''pam_mysql.so'' may also be located in ''/lib/security/'' instead of ''/usr/lib/security/''. I find Arch64 uses ''/usr/lib/security/pam_mysql.so'' and Arch32 uses ''/lib/security/pam_mysql.so''.<br />
<br />
* /etc/conf.d/saslauthd<br />
SASLAUTHD_OPTS="-m /var/run/saslauthd -r -a pam"<br />
<br />
* /usr/lib/sasl2/smtpd.conf<br />
pwcheck_method: saslauthd<br />
mech_list: plain login<br />
saslauthd_path: /var/run/saslauthd/mux<br />
log_level: 7<br />
<br />
==Put into production!==<br />
===Firing up services!===<br />
Run following command to start all services!<br />
for v in spamd mysqld httpd postfix dovecot;do /etc/rc.d/$v start ;done<br />
('''saslauthd''' if you plan to use SMTP-AUTH)<br />
<br />
If you plan to use Courier-IMAP, run following instead!<br />
for v in saslauthd spamd mysqld httpd postfix authdaemond courier-imap;do /etc/rc.d/$v start ;done<br />
('''saslauthd''' if you plan to use SMTP-AUTH)<br />
<br />
Go to following site to configure more stuff!<br />
* Postfix Admin<br />
http://YOUR_DOMAIN.TLD/postfixadmin/admin/<br />
(Default is '''USER''': admin '''PASS''': admin)<br />
I would look into Apache's documentation on .htaccess/.htpasswd and change out Postfix Admin's default admin page password.<br />
<br />
===Verify working===<br />
* Postfix<br />
Let's test see if Postfix is up and accepting connections.<br />
[root@monkey1 /etc/rc.d]# '''telnet localhost 25'''<br />
Trying 127.0.0.1...<br />
Connected to localhost.<br />
Escape character is '^]'.<br />
220 mail.YOUR_DOMAIN.TLD ESMTP Postfix (Arch Linux)<br />
'''ehlo YOUR_DOMAIN.TLD'''<br />
250-mail.YOUR_DOMAIN.TLD<br />
250-PIPELINING<br />
250-SIZE 10240000<br />
250-VRFY<br />
250-ETRN<br />
250-ENHANCEDSTATUSCODES<br />
250-8BITMIME<br />
250 DSN<br />
'''mail from: root@localhost'''<br />
250 2.1.0 Ok<br />
'''rcpt to: test@YOUR_DOMAIN.TLD'''<br />
250 2.1.5 Ok<br />
'''data'''<br />
354 End data with <CR><LF>.<CR><LF><br />
'''This is a test sending from root@localhost!'''<br />
'''.'''<br />
250 2.0.0 Ok: queued as 883E910C47B<br />
'''quit'''<br />
221 2.0.0 Bye<br />
Connection closed by foreign host.<br />
<br />
^^^^^^^^^^<br />
<br />
S-W-E-E-T! :)<br />
<br />
* Dovecot or Courier-IMAP<br />
Fire up your favorite mail client, that supports IMAP-SSL, and connect to your domain see if it works!<br />
<br />
* Spamassassin<br />
If you see something similar in your e-mail headers, Spamassassin is working!<br />
X-Spam-Checker-Version: SpamAssassin 3.2.3 (2007-08-08) on YOUR_DOMAIN.TLD<br />
X-Spam-Status: No, score=-0.2 required=3.0 tests=ALL_TRUSTED,MISSING_SUBJECT autolearn=no version=3.2.3<br />
<br />
* Postfix Admin<br />
Play around see everything works like it should.<br />
http://YOUR_DOMAIN.TLD/postfixadmin/<br />
<br />
* SquirrelMail<br />
http://YOUR_DOMAIN.TLD/squirrelmail/<br />
<br />
===Post-installation===<br />
If you firewalled your server, make sure the ports '''25 80 443 993''' (and '''465''' for SMTP-AUTH) are open!<br />
<br />
Don't forget to add services to your '''/etc/rc.conf'''!<br />
<br />
Any configuration files with '''YOUR_NEW_PASSWD''' in it you should '''''chmod 640''''' it!<br />
<br />
==Notes==<br />
Comments? Questions? Rants? Please let me know at '''''terii [-AT-] linuxmonkey [-DOT-] net'''''.<br />
<br />
You can also catch me on Freenode IRC under #archlinux; '''quad3d''', '''quad3datwork''', '''limlappy''', '''gangsterlicious''', or '''portofu'''.<br />
<br />
Thanks to [http://www.slicehost.com/ slicehost.com] for hosting my VPS! This guide is not possible without my VPS. Find this guide useful? Thinking about having your own VPS at slicehost.com? Ask me for my reference e-mail so I can get some credit! :)<br />
<br />
==See also==<br />
*[[Simple Virtual User Mail System]]<br />
*[[Courier MTA]]<br />
*[[Postfix]]</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Daemons_list&diff=242820Daemons list2013-01-03T09:30:36Z<p>Lfxgroove: added ifplugd to the list</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Daemons and system services]]<br />
[[zh-cn:Daemons List]]<br />
Here is a list of daemons. Note that any package can provide a daemon, so this list will never be complete. Please feel free to add any missing daemons here, in alphabetical order. You may have packages that include other daemons from the [[AUR]]. These files will likely be located in {{ic|/usr/lib/systemd/system/}}. <br />
For each daemon the name of the script (for [[rc.conf|initscripts]]) and of the service (for [[systemd]]) is given.<br />
{| border="1"<br />
!initscripts!!systemd!!Description<br />
|-<br />
|[[acpid]]||acpid.service||Delivers ACPI events.<br />
|-<br />
|[[Advanced Linux Sound Architecture|alsa]]||alsa-store.service<br />
alsa-restore.service<br />
||Advanced Linux Sound Architecture; provides device drivers for sound cards.<br />
|-<br />
|atd||atd.service||Run jobs queued for later execution.<br />
|-<br />
|[[Avahi|avahi-daemon]]||avahi-daemon.service||Allows programs to automatically find local network services.<br />
|-<br />
|[[Avahi|avahi-dnsconfd]]||avahi-dnsconfd.service||<br />
|-<br />
|[[Bitlbee|bitlbee]]||bitlbee.service||BitlBee IRC/IM gateway.<br />
|-<br />
|[[Bluetooth|bluetooth]]||bluetooth.service||Bluetooth daemon.<br />
|-<br />
|[[Connman|connmand]]||connman.service||Alternative network manager.<br />
|-<br />
|[[Chrony|chrony]]||chrony.service||Alternative NTP client/server designed for systems not online all the time.<br />
|-<br />
|[[ClamAV|clamav]]||clamd.service<br />
freshclamd.service<br />
||Antivirus.<br />
|-<br />
|[[CPU_Frequency_Scaling|cpupower]]||cpupower.service||Userspace tools for the kernel cpufreq subsystem<br />
|-<br />
|craftbukkit||''not yet implemented''||CraftBukkit Minecraft server<br />
|-<br />
|[[Cron|crond]]||cronie.service||Daemon to schedule and time events. The daemon name ''crond'' is used by at least two packages, {{Pkg|cronie}} and {{Pkg|dcron}}.<br />
|-<br />
|[[CUPS|cupsd]]||cupsd.service<br />
''or'' cups.service<br />
||Common UNIX Printing System daemon.<br />
|-<br />
|[[D-Bus|dbus]]||dbus.service||Message bus system for software communication.<br />
|-<br />
|[[Cron|dcron]]||dcron.service||Daemon to schedule and time events. The daemon name ''crond'' is used by at least two packages, {{Pkg|cronie}} and {{Pkg|dcron}}. {{Pkg|cronie}} is the default cron implementation for Arch.<br />
|-<br />
|[[dante|sockd]]||sockd.service||A circuit-level SOCKS client/server.<br />
|-<br />
|[[Deluge|deluged]]||deluged.service||Cross-platform and full-featured BitTorrent client.<br />
|-<br />
|[[Deluge|deluge-web]]||deluge-web.service||Cross-platform and full-featured BitTorrent client web UI.<br />
|-<br />
|[[Dhcpcd|dhcpcd]]||dhcpcd@.service||DHCP daemon. Insert the network interface after @ ('dhcpcd@eth0.service'). <br />
|-<br />
|[[Dovecot|dovecot]]||dovecot.service||IMAP and POP3 server. <br />
|-<br />
|[[Dropbox|dropboxd]]||''not yet implemented''||Cross-platform file synchronisation with version control.<br />
|-<br />
|[[FAM|fam]]||''deprecated''||File Alteration Monitor. (deprecated)<br />
|-<br />
|fancontrol||fancontrol.service||Fan control daemon (part of lm_sensors)<br />
|-<br />
|[[Fbsplash|fbsplash]]||''not yet implemented''||Graphical boot splash screen for the user.<br />
|-<br />
|[[FluidSynth|fluidsynth]]||fluidsynth.service||Software synthesizer<br />
|-<br />
|ftpd||ftpd.service||Inetutils ftp daemon<br />
|-<br />
|[[GDM|gdm]]||gdm.service||Gnome Display Manager (Login Screen)<br />
|-<br />
|[[Git|git-daemon]]||git-daemon.socket||GIT daemon<br />
|-<br />
|[[Console Mouse Support|gpm]]||gpm.service||Console mouse support.<br />
|-<br />
|[[HAL|hal]]||''deprecated''||Hardware Abstraction Layer. (Deprecated)<br />
|-<br />
|hddtemp||hddtemp.service||Hard drive temperature monitor daemon<br />
|-<br />
|healthd||healthd.service||A daemon which can be used to alert you in the event of a hardware health monitoring alarm (part of lm_sensors).<br />
|-<br />
|-<br />
|[[LAMP|httpd]]||httpd.service||Apache HTTP Server (Web Server)<br />
|-<br />
|[[hwclock]]||||Not a daemon as such, but on shutdown, updates hwclock to compensate for drift. Only run this daemon if ntpd is not running as both daemons adjust the hardware clock.<br />
|-<br />
|i8kmon||i8kmon.service||Monitor the cpu temperature and fan status on Dell Inspiron laptops.<br />
|-<br />
|ifplugd||ifplugd@<interface>.service, ie: ifplugd@eth0.service||Start/stop network on network cable plugged in/out.<br />
|-<br />
|iptables||iptables.service||Load firewall rules.<br />
|-<br />
|-<br />
|ip6tables||ip6tables.service||Load firewall rules for ipv6.<br />
|-<br />
|irqbalance||irqbalance.service||Irqbalance is the Linux utility tasked with making sure that interrupts from your hardware devices are handled in as efficient a manner as possible.<br />
|-<br />
|[[KDE|kdm]]||kdm.service||KDE Display Manager (Graphical Login)<br />
|-<br />
|krb5-kadmind||krb5-kadmind.service||Kerberos 5 administration server<br />
|-<br />
|krb5-kdc||krb5-kdc.service||Kerberos 5 KDC<br />
|-<br />
|krb5-kpropd||krb5-kpropd.service||Kerberos 5 propagation server<br />
|-<br />
|[[Laptop Mode Tools|laptop-mode]]||laptop-mode.service||Laptop Power Saving Tools<br />
|-<br />
|[[lighttpd]]||lighttpd.service||Lighttpd HTTP Server (Web Server).<br />
|-<br />
|[[LXDE|lxdm]]||lxdm.service||LXDE Display Manager (Graphical Login)<br />
|-<br />
|mdadm||mdadm.service||MD Administration (Linux Software RAID).<br />
|-<br />
|[[miniDLNA]]||minidlna.service||simple DLNA/UPnP media server<br />
|-<br />
|[[Music Player Daemon|mpd]]||mpd.service||Music Player Daemon.<br />
|-<br />
|[[MySQL|mysqld]]||mysqld.service||MySQL database server.<br />
|-<br />
|[[MythTV|mythbackend]]||mythbackend.service||Backend for the MythTV digital video recording/home theater software.<br />
|-<br />
|[[BIND|named]]||named.service||The Berkeley Internet Name Daemon (BIND) DNS server.<br />
|-<br />
|netfs||''unused, handled automatically, see''<br />
remote-fs.target<br />
''to manually execute scripts''<br />
||Mounts network file systems.<br />
|-<br />
|[[Netcfg|net-auto-wired]]||net-auto-wired.service||Netcfg replacement for {{ic|network}} - connects to wired network<br />
|-<br />
|[[Netcfg|net-auto-wireless]]||net-auto-wireless.service||Netcfg replacement for {{ic|network}} - connects to wireless network<br />
|-<br />
|[[Netcfg|net-profiles]]||netcfg.service<br />
netcfg@<profile-name>.service<br />
||Netcfg replacement for {{ic|network}} - connects to profiles<br />
|-<br />
|[[Configuring_Network|network]]||''(dynamic Ethernet)'' dhcpcd@<interface>.service||To bring up the network connections.<br />
|-<br />
|[[NetworkManager|networkmanager]]||NetworkManager.service<br />
NetworkManager-wait-online.service<br />
||Replaces {{ic|network}}, and provides configuration and detection for automatic network connections.<br />
|-<br />
|[[Nginx|nginx]]||nginx.service||Nginx HTTP Server and IMAP/POP3 proxy server (Web Server)<br />
|-<br />
|nscd||nscd.service||Name service cache daemon<br />
|-<br />
|[[Network Time Protocol daemon|ntpd]]||ntpd.service||Network Time Protocol daemon (client and server).<br />
|-<br />
|[[Ntop|Ntop]]||ntop.service||Ntop is a network traffic probe based on libcap.<br />
|-<br />
|[[OpenNTPD|openntpd]]||openntpd.service||alternate Network Time Protocol daemon (client and server).<br />
|-<br />
|osspd||osspd.service||OSS Userspace Bridge.<br />
|-<br />
|[[OpenVPN|openvpn]]||openvpn@<profile-name>.service||One for each vpn conf file saved like /etc/openvpn/<profile-name>.conf<br />
|-<br />
|[[Pdnsd|pdnsd]]||pdnsd.service||Proxy DNS server with permanent caching.<br />
|-<br />
|[[Nginx#1st_Method_.22New.22_.28as_of_PHP_5.3.3.29|php-fpm]]||php-fpm.service||FastCGI Process Manager for PHP<br />
|-<br />
|[[OSS|oss]]||oss.service||Open Sound System. Alternative to ALSA.<br />
|-<br />
|[[PostgreSQL|postgresql]]||postgresql.service||PostgreSQL database server.<br />
|-<br />
|[[Postfix|postfix]]||postfix.service||<br />
|-<br />
|[[powernowd]]||''not yet implemented''||To adjust speed of CPU depending on system load. See also [[CPU Frequency Scaling]]<br />
|-<br />
|[[PPTP Server|pptpd]]||pptpd.service||A Virtual Private Network (VPN) server using the Point-to-Point Tunneling Protocol (PPTP).<br />
|-<br />
|[[Prosody|prosody]]||prosody.service||XMPP server.<br />
|-<br />
|[[pppd|Pppd]]||ppp@provider.service||A daemon which implements the Point-to-Point Protocol for dial-up networking.<br />
|-<br />
|[[preload]]||preload.service||Makes applications run faster by prefetching binaries and shared objects.<br />
|-<br />
|[[psd]]||psd.service||Manages your browser's profile in tmpfs and periodically sync it back to your physical disk.<br />
|-<br />
|pure-ftpd||''not yet implemented''||FTP server.<br />
|-<br />
|[[readahead]]||systemd-readahead-collect.service<br />
systemd-readahead-done.service<br />
<br />
systemd-readahead-drop.service<br />
<br />
systemd-readahead-replay.service<br />
||Readahead for faster boot<br />
|-<br />
||rfkill||rfkill-block@.service<br />
rfkill-unblock@.service<br />
||(Un)block radio devices. A block@all or unblock@all instance (not to be enabled simultaneously) is started before any unblock@device or block@device, respectively.<br />
|-<br />
|[[Rsync|rsyncd]]||rsyncd.service||Rsync daemon.<br />
|-<br />
|[[Rsyslog|rsyslogd]]||rsyslog.service||The latest version of a system logger.<br />
|-<br />
|[[samba]]||smbd.service<br />
nmbd.service<br />
<br />
winbindd.service<br />
||File and print services for Microsoft Windows clients.<br />
|-<br />
|[[USB_Scanner_Support|saned]]||saned@.service||To share the scanner system over network.<br />
|-<br />
|[[saslauthd]]||saslauthd.service||SASL authentication daemon<br />
|-<br />
|sensord||sensord.service||Sensor information logging daemon (part of lm_sensors)<br />
|-<br />
|[[Lm sensors|sensors]]||lm_sensors.service||Hardware (temperature, fans etc) monitoring.<br />
|-<br />
|[[SLiM|slim]]||slim.service||Simple Login Manager<br />
|-<br />
|[[SMART|smartd]]||smartd.service||Self-Monitoring, Analysis, and Reporting Technology (S.M.A.R.T) Hard Disk Monitoring<br />
|-<br />
|[[Samba#smbnetfs|smbnetfs]]||smbnetfs.service||To automatically mount Samba/Microsoft network shares.<br />
|-<br />
|snmpd||snmpd.service||A suite of applications used to implement SNMP<br />
|-<br />
|soundmodem||''not yet implemented''||Multiplatform Soundcard Packet Radio Modem<br />
|-<br />
|[[SOHO Postfix|spamd]]||spamassassin.service|| e-mail spam filtering service.<br />
|-<br />
|[[Secure Shell|sshd]]||sshd.service (permanent)<br />
sshd.socket (on-demand)<br />
||OpenSSH (secure shell) daemon.<br />
|-<br />
|stbd||''deprecated''||This daemon was previously necessary for gnome-system-tools. However, as of gnome-tools 2.28, it is no longer needed.<br />
|-<br />
|[[stunnel]]||stunnel.service||Allows encrypting arbitrary TCP connections inside SSL.<br />
|-<br />
|svnserve||svnserve.service||Subversion server<br />
|-<br />
|syslogd||''deprecated''||This was the older and basic system logger.<br />
|-<br />
|[[syslog-ng]]||syslog-ng.service||System logger next generation.<br />
|-<br />
|[[Timidity|timidity++]]||timidity.service||Software synthesizer for MIDI.<br />
|-<br />
|[[Tor|tor]]||tor.service||Onion routing for anonymous communication.<br />
|-<br />
|[[Transmission|transmissiond]]||transmission.service||Bit Torrent Daemon.<br />
|-<br />
|[[Ufw|ufw]]||ufw.service||Uncomplicated FireWall.<br />
|-<br />
|[[VirtualBox|vboxservice]]||vboxservice.service||VirtualBox Guest Service<br />
|-<br />
|[[Very Secure FTP Daemon|vsftpd]]||vsftpd.service (permanent)<br />
vsftpd.socket (on-demand)<br />
vsftpd-ssl.service (permanent)<br />
vsftpd-ssl.socket (on-demand)<br />
||FTP server.<br />
|-<br />
|[[wicd]]||wicd.service||Combine with dbus to replace {{ic|network}}, a lightweight alternative to NetworkManager.<br />
|-<br />
|[[x11vnc]]||x11vnc.service||VNC remote desktop daemon <br />
|-<br />
|}</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Pm-utils&diff=237032Pm-utils2012-11-27T16:36:25Z<p>Lfxgroove: /* Editing GRUB2's defaults */ Added notice about UUID= part needed if you specify that instead of /dev/sd*</p>
<hr />
<div>[[Category:Power management]]<br />
[[it:Pm-utils]]<br />
[[ru:Pm-utils]]<br />
[[zh-CN:Pm-utils]]{{DISPLAYTITLE:pm-utils}}<br />
{{Article summary start}}<br />
{{Article summary text|Describes installing, configuring, using and troubleshooting pm-utils, the new suspend and powerstate setting framework.}}<br />
{{Article summary heading|Related articles}}<br />
{{Article summary wiki|Uswsusp}}<br />
{{Article summary wiki|Tuxonice}}<br />
{{Article summary end}}<br />
'''pm-utils''' is a suspend and powerstate setting framework. It is designed to replace such scripts as those provided by the {{ic|powersave}} package.<br />
<br />
pm-utils is a collection of shell scripts that wrap the kernel mode suspend/resume with the various hacks. These hacks are needed to work around bugs in drivers and subsystems that are not yet aware of suspend. It is easily extensible by putting custom hooks into a directory, which can either be done by the system administrator or those hooks can be part of a package, especially if this package needs special attention during a system suspend or power state transition.<br />
<br />
A lesser known feature is one that mimics toggling done by [[Laptop Mode Tools]], although the responsible scripts have been deleted from the Arch Linux package.<br />
<br />
Used in conjunction with the [[cpupower]] package, notebook (and desktop) owners are provided with a complete power management suite.<br />
<br />
== Installation ==<br />
<br />
[[pacman|Install]] the {{Pkg|pm-utils}} package which is available in the [[Official Repositories|official repositories]].<br />
<br />
{{Note|If you run into issues when resuming video, it might be necessary to also install {{Pkg|vbetool}} from the [[Official Repositories|official repositories]].}}<br />
<br />
{{Note|If you are starting from a clean install, make sure that you have {{Pkg|acpi}} installed.}}<br />
<br />
Run {{ic|pm-suspend}}, {{ic|pm-suspend-hybrid}} or {{ic|pm-hibernate}} as root to trigger suspend manually. The suspend scripts write log to {{ic|/var/log/pm-suspend.log}}.<br />
<br />
=== suspend backend ===<br />
<br />
The Arch Linux package ships with support for the following backends: {{ic|kernel}}, {{ic|tuxonice}} and {{ic|uswsusp}} which can be seen from command:<br />
pacman -Ql pm-utils | grep module.d<br />
<br />
Suspend backend is specified by the {{ic|SLEEP_MODULE}} configuration variable in {{ic|/etc/pm/config.d}} and defaults to the {{ic|kernel}} backend. To use the alternative suspend backends the respective packages need to be installed. Both of these are available in the [[Arch User Repository]]:<br />
* uswsusp - {{AUR|uswsusp-git}}<br />
* tuxonice - {{AUR|linux-ice}} / [[linux-pf]]<br />
<br />
Furthermore, {{Pkg|pm-utils}} ships with its own video quirks database in {{ic|/usr/lib/pm-utils/video-quirks/}}.<br />
<br />
== Basic Configuration ==<br />
=== Standby / Suspend to RAM ===<br />
In the ideal case, running {{ic|pm-suspend}} as root should initiate suspend to memory, meaning that all running state will be preserved in RAM and all components other than RAM will be shut down to conserve power. Pressing the power button should initiate a resume from this state.<br />
<br />
{{Note|It is always recommended to put your network drivers in SUSPENDED_MODULES because most wireless drivers are known to cause issues after standby. Intel's iwlwifi, Atheros' ath5k and Realtek's r8* drivers were all reported to have issues after resume on the forums. Iwlwifi even drops to 1Mpbs connection if it is not reloaded after resume.}} <br />
<br />
In some cases, it is possible that running {{ic|pm-suspend}} causes hangs or other issues. This may be due to specific "misbehaving" modules. If you know which modules could cause such issues, adding a {{ic|SUSPEND_MODULES}} config to {{Ic|/etc/pm/config.d/modules}} of the form:<br />
SUSPEND_MODULES="uhci_hd button ehci_hd iwlwifi"<br />
should cause these modules to be specifically unloaded before suspend and reloaded after resume.<br />
<br />
To configure invoking {{ic|pm-suspend}} automatically on power events like laptop lid close, please refer to [[Acpid]].<br />
<br />
=== Hibernation (suspend2disk) ===<br />
In order for suspend2disk (hibernate) to work, the parameter {{ic|1=resume=SWAP_PARTITION}} has to be passed to the [[Kernel parameters]] (where {{ic|SWAP_PARTITION}} is either your swap device, i.e. {{ic|/dev/sda'''X'''}}, or your swap UUID) .Consult [[Kernel parameters]] for more info.<br />
<br />
==== Editing GRUB2's defaults ====<br />
The easiest way to modify the kernel parameters is to edit the default for GRUB2 held in {{ic|/etc/default/grub}}. If {{ic|/dev/sda5}} is your swap partition then change {{ic|GRUB_CMDLINE_LINUX}} to:<br />
<br />
{{bc|1=GRUB_CMDLINE_LINUX="resume=/dev/sda5"}}<br />
<br />
And if you use the UUID instead don't forget to specify that, ie: (to find the UUID you could use {{ic|blkid}} as root)<br />
<br />
{{bc|1=GRUB_CMDLINE_LINUX="resume=UUID=xxxxx-xxxx-xxxxxx-xxxxxx"}}<br />
<br />
Don't forget to run {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} afterwards.<br />
<br />
==== Including GRUB2's os-prober lines ====<br />
According to the [http://wiki.debian.org/Grub#Configuring_grub_v2 debian wiki], here is a handy solution for GRUB2 that will insert the resume line with the swap device the system is using when running the script. Replace (line 141):<br />
{{bc|1=linux ${rel_dirname}/${basename} root=${linux_root_device_thisversion} ro ${args} }}<br />
with:<br />
{{bc|<nowiki>linux ${rel_dirname}/${basename} root=${linux_root_device_thisversion} ro ${args} resume=`swapon -s | grep '/dev/sd.[0-9]' -o`</nowiki>}}<br />
<br />
When the machine is placed into hibernation, it will now move all data from RAM to the swap partition.<br />
<br />
For discussion regarding permanence, please refer to [https://bbs.archlinux.org/viewtopic.php?pid=886789#p88678 this thread].<br />
<br />
Even if your swap partition is smaller than RAM, you still have a big chance in hibernating successfully. According to [http://www.mjmwired.net/kernel/Documentation/power/interface.txt kernel documentation]: "''{{ic|/sys/power/image_size}} controls the size of the image created by the suspend-to-disk mechanism [...] which is set to 2/5 of available RAM by default. [...] The suspend-to-disk mechanism will do its best to ensure the image size will not exceed that number.''" You may either decrease it due to a small swap partition or increase it in purpose of possible hibernation speed up.<br />
<br />
{{Warning|You may have to add the {{ic|resume}} hook to {{ic|/etc/mkinitcpio.conf}}, see [[Pm-utils#Mkinitcpio_Resume_Hook|below]]!}}<br />
<br />
<br />
==== For LILO users ====<br />
For LILO users, you just need to add a line {{ic|1=append=" resume=/dev/sda5"}}, assuming {{ic|/dev/sda5}} is your swap partition.<br />
<br />
==== For Syslinux users ====<br />
Update syslinux.cfg, normally located at {{ic|1=/boot/syslinux/syslinux.cfg}}, to include the {{ic|1=resume=/dev/location/of/swap}}<br><br />
Example:<br />
{{bc|<nowiki> <br />
LABEL arch<br />
MENU LABEL Arch Linux<br />
LINUX ../vmlinuz-linux<br />
APPEND cryptdevice=/dev/sda2:vgroot resume=/dev/mapper/vgroot-swap root=/dev/mapper/vgroot-root ro <br />
INITRD ../initramfs-linux.img<br />
</nowiki>}}<br />
<br />
<br />
=== Mkinitcpio Resume Hook ===<br />
If your system '''still''' doesn't resume from hibernation, even after you've added the proper lines to your grub config files, your system may require the {{ic|resume}} hook be added to the initrd image (even if you use [[LVM]]), otherwise the kernel will '''not''' resume. You can see if this is happening if the hibernation works fine, no error messages appear in {{ic|/var/log/pm-suspend.log}} and the kernel logs the following message: "PM: Hibernation image not present or could not be loaded." <br />
<br />
To add the resume hook, edit {{ic|/etc/mkinitcpio.conf}} as root and add {{ic|resume}} to the HOOKS array. {{ic|resume}} must be placed ''after'' {{ic|ide}}, {{ic|scsi}}, {{ic|sata}} and/or {{ic|lvm2}}, but before {{ic|filesystems}}. <br />
HOOKS="base udev autodetect ide scsi sata lvm2 '''''resume''''' filesystems"<br />
<br />
Note that this is an example, and your HOOKS array may look different.<br />
<br />
Finally, you must rebuild the initrd image for these changes to take effect:<br />
# mkinitcpio -p linux<br />
<br />
{{Note|If you use a custom kernel, then you might have to change the value of the {{ic|-p}} option.}}<br />
<br />
=== Suspend/Hibernate as regular user ===<br />
<br />
Three methods are available to suspend without the need for a root password: using [[Udev]], using UPower, and giving the user the appropriate permissions with [[sudo|visudo]].<br />
<br />
==== UPower method ====<br />
<br />
Install {{Pkg|upower}}. To suspend to RAM:<br />
$ dbus-send --system --print-reply --dest="org.freedesktop.UPower" \<br />
/org/freedesktop/UPower org.freedesktop.UPower.Suspend<br />
<br />
To suspend to disk (hibernate):<br />
$ dbus-send --system --print-reply --dest="org.freedesktop.UPower" \<br />
/org/freedesktop/UPower org.freedesktop.UPower.Hibernate<br />
<br />
==== User Permission Method ====<br />
<br />
Because the {{Pkg|pm-utils}} scripts must be run as root, you may want to make the scripts accessible to normal users by running sudo without the root password. To do so, edit the {{ic|/etc/sudoers}} file with {{ic|visudo}} as root. For more information, see [[sudo]].<br />
<br />
Add the following lines, replacing {{ic|''username''}} with your own user name, then save and exit {{ic|visudo}}:<br />
''username'' ALL = NOPASSWD: /usr/sbin/pm-hibernate<br />
''username'' ALL = NOPASSWD: /usr/sbin/pm-suspend<br />
<br />
Or you can enable it for a group, using the following lines, replacing {{ic|''group''}}:<br />
%''group'' ALL = NOPASSWD: /usr/sbin/pm-hibernate<br />
%''group'' ALL = NOPASSWD: /usr/sbin/pm-suspend<br />
<br />
{{Note|These must come after any user privilege specifications, e.g., {{ic|1=username ALL=(ALL) ALL}}, or they will not work.}}<br />
<br />
You can now run the scripts without a password by simply running:<br />
$ sudo pm-hibernate<br />
<br />
or:<br />
<br />
$ sudo pm-suspend<br />
<br />
Also, add yourself to the {{ic|power}} [[Users and Groups|group]] so that way using things like applets to do suspend will work. If you do not do this, when you try to use suspend though things like [[GNOME]]'s shutdown applet, your computer will just play a very annoying loud triple beep and lock the screen.<br />
# gpasswd -a ''username'' power<br />
<br />
You should now be able to use your [[Desktop Environment]]'s power management tools to automatically suspend or hibernate when doing things like closing the laptop lid, running low on battery power, etc.<br />
<br />
===Power saving===<br />
pm-utils supports running commands depending on whether the system is connected to the AC adapter or not; therefore, a script has to be created inside the folder {{ic|/etc/pm/power.d/}}. An example of such a script can be found in the [http://crunchbanglinux.org/forums/post/110148/#p110148 crunchbang forum]. Be aware that upower must be running in order to detect changing AC states [https://bbs.archlinux.org/viewtopic.php?id=132125 (see more information)].<br />
<br />
====Change brightness depending on AC state====<br />
One possible example looks as follows and changes brightness according to the AC state. Create a file called {{ic|/etc/pm/power.d/00-brightness}} with the following content and change the path to the brightness setting as well as the value written into the file with echo according to your system.<br />
<br />
#!/bin/bash<br />
<br />
case $1 in<br />
true)<br />
echo "Enable screen power saving"<br />
echo 5 > /sys/class/backlight/acpi_video0/device/backlight/acpi_video0/brightness<br />
;;<br />
false)<br />
echo "Disable screen power saving"<br />
echo 14 > /sys/class/backlight/acpi_video0/device/backlight/acpi_video0/brightness<br />
;;<br />
esac<br />
<br />
===Suspend on idle/inactivity===<br />
<br />
One method relies on xautolock program. Add following: {{ic|xautolock -time 30 -locker "sudo pm-suspend" &}} to {{ic|~/.xinitrc}}. This implies that {{ic|pm-suspend}} is called after 30 minutes of inactivity.<br />
<br />
=== Using Swap file instead of regular swap partition ===<br />
<br />
If you want use swap file instead of regular swap partition [[Swap#Swap_file_resuming|read this]].<br />
<br />
== Advanced Configuration ==<br />
The main configuration file is {{ic|/usr/lib/pm-utils/defaults}}. You ''should not edit this file'', since after a package update it might be overwritten with the default settings. Put your config file into {{ic|/etc/pm/config.d/}} instead.<br />
You can just put a simple text file with<br />
SUSPEND_MODULES="button uhci_hcd"<br />
named {{ic|modules}} or {{ic|config}} into {{ic|/etc/pm/config.d}} and it will override the settings in the system-wide configuration file.<br />
<br />
=== Available variables for use in config files ===<br />
;SUSPEND_MODULES="button": the list of modules to be unloaded before suspend<br />
;SLEEP_MODULE="tuxonice uswsusp kernel": the default sleep/wake systems to try<br />
;HIBERNATE_MODE="shutdown": forces the system to shut down rather than reboot<br />
<br />
=== Disabling a hook ===<br />
If a hook is run which you do not like or which you think is not useful or even harmful, we would appreciate a bug report for that.<br />
You can however easily disable hooks by just creating an empty file corresponding to the hook in {{ic|/etc/pm/sleep.d/}}. Say you want to disable the hook {{ic|/usr/lib/pm-utils/sleep.d/45pcmcia}}, you can do this easily by calling<br />
# touch /etc/pm/sleep.d/45pcmcia<br />
Do not set the executable bit on that dummy-hook.<br />
<br />
Note: Make sure you create the dummy files in the appropriate directory. For example if you are trying to disable hooks in /usr/lib/pm-utils/power.d, you will need to place the dummy file in /etc/pm/power.d.<br />
<br />
==== Alternative method ====<br />
Create a file in {{ic|/etc/pm/config.d}} with the modules you want to blacklist in the {{ic|HOOK_BLACKLIST}} variable.<br />
For example, to manage power saving yourself, use:<br />
HOOK_BLACKLIST="hal-cd-polling intel-audio-powersave journal-commit laptop-mode pcie_aspm readahead sata_alpm sched-powersave xfs_buffer wireless"<br />
<br />
=== Creating your own hooks ===<br />
If you want to do something specific to your setup during suspend or hibernate, then you can easily put your own hook into {{ic|/etc/pm/sleep.d}}. The hooks in this directory will be called in alphabetic order during suspend (that is the reason their names all start with 2 digits, to make the ordering explicit) and in the reverse order during resume. The general convention to be followed on number ordering is:.<br />
;00 - 49: User and most package supplied hooks. If a hook assumes that all of the usual services and userspace infrastructure is still running, it should be here.<br />
;50 - 74: Service handling hooks. Hooks that start or stop a service belong in this range. At or before 50, hooks can assume that all services are still enabled.<br />
;75 - 89: Module and non-core hardware handling. If a hook needs to load/unload a module, or if it needs to place non-video hardware that would otherwise break suspend or hibernate into a safe state, it belongs in this range. At or before 75, hooks can assume all modules are still loaded.<br />
;90 - 99: Reserved for critical suspend hooks.<br />
<br />
I am showing a pretty useless demonstration hook here, that will just put some informative lines into your log file:<br />
<br />
#!/bin/bash<br />
case $1 in<br />
hibernate)<br />
echo "Hey guy, we are going to suspend to disk!"<br />
;;<br />
suspend)<br />
echo "Oh, this time we are doing a suspend to RAM. Cool!"<br />
;;<br />
thaw)<br />
echo "Oh, suspend to disk is over, we are resuming..."<br />
;;<br />
resume)<br />
echo "Hey, the suspend to RAM seems to be over..."<br />
;;<br />
*) echo "Somebody is calling me totally wrong."<br />
;;<br />
esac<br />
<br />
Put this into {{ic|/etc/pm/sleep.d/66dummy}}, do a {{ic|chmod +x /etc/pm/sleep.d/66dummy}} and it will spew some useless lines during suspend and resume.<br />
<br />
{{Warning|All the hooks run as root. This means that you need to be careful when creating temporary files, check that the {{ic|PATH}} environment variable is set correctly, etc. to avoid security problems.}}<br />
<br />
== How it works ==<br />
The concept is quite easy: the main script ({{ic|pm-action}}, called via symlinks as either {{ic|pm-suspend}}, {{ic|pm-hibernate}} or {{ic|pm-suspend-hybrid}}) executes so-called "hooks", executable scripts, in the alphabetical sorted order with the parameter {{ic|suspend}} (suspend to RAM) or {{ic|hibernate}} (suspend to disk).<br />
Once all hooks are done, it puts the machine to sleep. After the machine has woken up again, all those hooks are executed in reverse order with the parameter {{ic|resume}} (resume from RAM) or {{ic|thaw}} (resume from disk).<br />
The hooks perform various tasks, such as preparing the bootloader, stopping the Bluetooth subsystem, or unloading of critical modules.<br />
<br />
Both {{ic|pm-suspend}} and {{ic|pm-hibernate}} are usually called from [[Udev]], initiated by desktop applets like {{Pkg|gnome-power-manager}} or {{ic|kpowersave}}.<br />
<br />
{{Note|{{ic|suspend-hybrid}} is a placeholder right now -- it is not completely implemented.}}<br />
<br />
There is also the possibility to set the machine into high-power and low-power mode, the command {{ic|pm-powersave}} is used with an additional parameter of {{ic|true}} or {{ic|false}}. It works basically the same as the suspend framework.<br />
<br />
The hooks for suspend are placed in<br />
;{{ic|/usr/lib/pm-utils/sleep.d}}: distribution / package provided hooks<br />
;{{ic|/etc/pm/sleep.d}}: hooks added by the system administrator<br />
<br />
The hooks for the power state are placed in <br />
;{{ic|/usr/lib/pm-utils/power.d}}: distribution / package provided hooks<br />
;{{ic|/etc/pm/power.d}}: hooks added by the system administrator<br />
<br />
Hooks in {{ic|/etc/pm/}} take precedence over those in {{ic|/usr/lib/pm-utils/}}, so the system administrator can override the defaults provided by the distribution.<br />
<br />
=== Pm-suspend internals ===<br />
<br />
This outlines the internal actions when {{ic|pm-suspend}} is run, describing how {{ic|pm-utils}} gracefully falls back onto the kernel method if the requirements of other methods are not met.<br />
<br />
$ pm-suspend<br />
<br />
The first step is set-up preliminary variables and source parent scripts:<br />
export STASHNAME=pm-suspend<br />
export METHOD="$(echo ${0##*pm-} |tr - _)"<br />
. "/usr/lib/pm-utils/pm-functions"<br />
<br />
The variable {{Ic|METHOD}} is extracted from the executable name, ''suspend'' from {{ic|pm-suspend}} and ''hibernate'' from {{ic|pm-hibernate}}.<br />
<br />
The location of runtime configuration parameters is defined in {{Ic|/usr/lib/pm-utils/pm-functions}} as ''PM_UTILS_RUNDIR="/var/run/pm-utils"'' and ''STORAGEDIR="${PM_UTILS_RUNDIR}/${STASHNAME}/storage"''. Therefore ''STORAGEDIR="/var/run/pm-utils/pm-suspend/storage"''; this is where {{ic|pm-suspend}} will cache its configuration. Disabled hooks are stored as plain text files with the hook name prefixed by "''disable_hook:''". Configuration parameters are appended to the ''parameters'' file:<br />
$ ls -lah /var/run/pm-utils/pm-suspend/storage/<br />
-rw-r--r-- 1 root root 20 May 19 09:57 disable_hook:99video<br />
-rw-r--r-- 1 root root 0 May 19 02:59 parameters<br />
-rw-r--r-- 1 root root 247 May 19 02:59 parameters.rm<br />
-rw-r--r-- 1 root root 9 May 19 02:59 state:cpu0_governor<br />
-rw-r--r-- 1 root root 9 May 19 02:59 state:cpu1_governor<br />
<br />
Then {{Ic|pm-functions}} will source the files located in {{Ic|/etc/pm/config.d/}} in addition to {{Ic|/usr/lib/pm-utils/defaults}}. Upon returning, {{Ic|pm-functions}} will proceed to source the files specified by '''$SLEEP_METHOD''' as {{Ic|/usr/lib/pm-utils/module.d/$SLEEP_METHOD[...]}} if they exist:<br />
for mod in $SLEEP_MODULE; do<br />
mod="${PM_UTILS_LIBDIR}/module.d/${mod}"<br />
[ -f "$mod" ] || continue<br />
. "$mod"<br />
done<br />
<br />
Otherwise, if '''$SLEEP_MODULE''' is empty, {{Ic|do_suspend()}} will be set to the kernel backend as described above:<br />
if [ -z "$SUSPEND_MODULE" ]; then<br />
if grep -q mem /sys/power/state; then<br />
SUSPEND_MODULE="kernel"<br />
do_suspend() { echo -n "mem" >/sys/power/state; }<br />
elif [ -c /dev/pmu ] && pm-pmu --check; then<br />
SUSPEND_MODULE="kernel"<br />
do_suspend() { pm-pmu --suspend; }<br />
elif grep -q standby /sys/power/state; then<br />
SUSPEND_MODULE="kernel"<br />
do_suspend() { echo -n "standby" >/sys/power/state; }<br />
fi<br />
fi<br />
<br />
Assuming '''$SLEEP_MODULE''' is not empty and {{Ic|uswsusp}} is specified, {{Ic|/usr/lib/pm-utils/module.d/uswsusp}} is executed. This script checks several requirements (these are the requirements for being able to use uswsusp):<br />
* [ -z $SUSPEND_MODULE ]<br />
* command_exists s2ram<br />
* grep -q mem /sys/power/state || ( [ -c /dev/pmu ] && pm-pmu --check; );<br />
If these requirements are met, do_suspend() is defined as:<br />
do_suspend()<br />
{<br />
uswsusp_get_quirks<br />
s2ram --force $OPTS<br />
}<br />
Most importantly, the {{Ic|uswsusp}} module runs:<br />
add_before_hooks uswsusp_hooks<br />
add_module_help uswsusp_help<br />
The first function, ''add_before_hook'' disables the '''pm-utils''' hooks '''99video''' since this functionality is subsumed by '''s2ram'''.<br />
The second function, ''add_module_help'', adds uswsusp-module-specific help, which in essence replaces the help function provided by '''99video'''.<br />
<br />
Back to {{Ic|pm-suspend}}:<br />
command_exists "check_$METHOD" && command_exists "do_$METHOD"<br />
"check_$METHOD"<br />
This verifies that the ''check_suspend'' and ''do_suspend'' methods have been defined. The ''check_suspend'' method simply verifies that $SUSPEND_MODULE is not empty:<br />
<br />
check_suspend() { [ -n "$SUSPEND_MODULE" ]; }<br />
<br />
Lastly, {{Ic|pm-suspend}} must run all hooks that have not been disabled, sync file-system buffers, and run ''do_suspend'':<br />
if run_hooks sleep "$ACTION $METHOD"; then<br />
# Sleep only if we know how and if a hook did not inhibit us.<br />
log "$(date): performing $METHOD"<br />
sync<br />
"do_$METHOD" || r=128<br />
log "$(date): Awake."<br />
<br />
The method ''run_hooks'' is a wrapper for ''_run_hooks'', which the case of {{ic|pm-suspend}} is called as ''run_hooks sleep "suspend suspend"''. Given that:<br />
PARAMETERS="${STORAGEDIR}/parameters"<br />
PM_UTILS_LIBDIR="/usr/lib/pm-utils"<br />
PM_UTILS_ETCDIR="/etc/pm"<br />
<br />
The method ''_run_hooks'', will for each hook in ''"${PM_UTILS_LIBDIR}/$1.d"'' and ''"${PM_UTILS_ETCDIR}/$1.d"'', check that sleep has not been inhibited and update the runtime parameters stored in ''$PARAMETERS'' before running each hook via ''run_hook $hook $2''. In the case of Suspend-to-RAM, all the hooks in ''{/usr/lib/pm-utils/sleep.d/,/etc/pm/sleep.d/}'' will be enumerated, and ''run_hook'' will be passed the parameters ''$hook'' and "''suspend suspend''". The method ''run_hook'' uses the ''hook_ok'' function to verify that the hook has not been disabled before executing the hook with the "''suspend suspend''" parameters.<br />
<br />
== Troubleshooting ==<br />
If suspend or hibernate did not work correctly, you will probably find some information in the log file {{ic|/var/log/pm-suspend.log}}. For example, which hooks were run and what the output of them was should be in that log file.<br />
<br />
Also, check the output of the {{ic|pm-is-supported}} command. This command (with the {{ic|--hibernate}} or {{ic|--suspend}} flag) will do some sanity checking and report any errors it finds in your configuration. It will not detect all possible errors, but may still be useful.<br />
<br />
=== Segmentation faults === <br />
If you experience segmentation faults that might result in an unresponsive system and missing keys then try to set the UUID in the resume-path in {{ic|/boot/grub/menu.lst}} as explained [[#Hibernation (suspend2disk)|above]].<br />
<br />
=== Reboot instead of resume from suspend ===<br />
<br />
This problem started when saving NVS area during suspend was introduced (in 2.6.35-rc4) ([http://www.spinics.net/lists/linux-acpi/msg29521.html mailing list post]). However, it is known that this mechanism does not work on all machines, so the kernel developers allow the user to disable it with the help of the {{ic|1=acpi_sleep=nonvs}} kernel command line option. This option could be pass to the kernel through [[GRUB]] options by editing the file {{ic|/boot/grub/menu.lst}} (GRUB 0.97) on the {{ic|kernel}} line.<br />
<br />
=== Resume from suspend shuts down instead of wake up ===<br />
On an Acer Aspire AS3810TG, resuming from suspend shuts down the computer instead of waking it up. If you experience a similar issue, try passing the parameter {{ic|1=i8042.reset=1}} to your kernel. In [[GRUB2]], the line in {{ic|/boot/grub/grub.cfg}} should be something like this:<br />
linux /vmlinuz-linux root=/dev/vg00/root resume=/dev/vg00/swap i8042.reset=1 ro<br />
<br />
Although I have not tested this, you could also set this parameter live without having to restart by doing:<br />
# sysctl -e -w i8042.reset=1<br />
<br />
=== Blank screen when waking from suspend ===<br />
Some laptops (e.g. Dell Inspiron Mini 1018) will just show a black screen with no backlight after resuming from suspend. If this happens to you, try going into the BIOS of the laptop and disabling Intel SpeedStep if it is present.<br />
<br />
You could also try, without disabling SpeedStep, creating a quirk in {{ic|/etc/pm/sleep.d/}} with this content (requires {{Pkg|vbetool}}):<br />
{{bc|#!/bin/sh<br />
#<br />
case "$1" in<br />
suspend)<br />
;;<br />
resume)<br />
sleep 5<br />
vbetool dpms off<br />
vbetool dpms on<br />
;;<br />
*) exit $NA<br />
;;<br />
esac}}<br />
save it as you want but with a {{ic|00}} in front of the name so this is called last when resuming; remember to {{ic|chmod +x}} the script.<br />
Try adjusting the {{ic|sleep}} time if the other commands are called too soon, or if it works well, you can also try removing that line.<br />
<br />
Some other laptops (e.g. Toshiba Portégé R830) will just show a black screen with no backlight after resuming from suspend, with fans blowing at top speed. If this is what you're seeing, try going into the BIOS and disable the VT-d virtualization setting by switching to "VT-x only".<br />
<br />
=== VirtualBox problems ===<br />
The VirtualBox kernel modules cause {{ic|pm-suspend}} and {{ic|pm-hibernate}} to fail on some laptops. (See [https://bbs.archlinux.org/viewtopic.php?id=123354 this discussion]). Instead of suspending or hibernating, the system freezes and indicator LEDs blink (the suspend indicator in the case of ThinkPads and the Caps Lock and Scroll Lock indicators in the case of the MSI Wind U100). The {{ic|pm-suspend}} and {{ic|pm-hibernate}} logs appear normal.<br />
<br />
The problem can be fixed by removing the modules before suspension or hibernation and reloading them afterwards. That can be accomplished through a script:<br />
{{bc|1=<br />
#!/bin/sh<br />
<br />
rmmod vboxdrv<br />
pm-hibernate<br />
modprobe vboxdrv<br />
}}<br />
<br />
{{Note|Some users reported that it is sufficient to rebuild the kernel module by running {{ic|vboxbuild}} as root.}}<br />
<br />
=== Hibernate with missing swap partition ===<br />
If you try to hibernate without an active swap partition, your system will look like it is going into hibernate, and then immediately resume again. There are no error messages warning you that there is no swap partition, even when verbose logging is activated, so this problem can be very hard to debug. On my system, the swap partition was somehow corrupted and deactivated, so this may happen even if you set up a swap partition during install. If hibernate displays this behaviour, make sure that you actually have a swap partition that is being used as such. The output of the {{ic|blkid}} command should look e.g. like<br />
{{bc|1=<br />
# blkid<br />
/dev/sda1: UUID="00000-000-000-0000000" TYPE="ext2" <br />
/dev/sda2: UUID="00000-000-000-0000000" TYPE="ext4"<br />
/dev/sda3: UUID="00000-000-000-0000000" TYPE="ext4"<br />
/dev/sda4: UUID="00000-000-000-0000000" TYPE="swap"<br />
}}<br />
with one of the lines having {{ic|"swap"}} as the type. If this is not the case, consult [[Swap#Swap partition]] for instructions on re-creating/activating the swap partition.<br />
<br />
=== Black screen with unblinking cursor when trying to suspend ===<br />
If you get a black screen with unblinking cursor when trying to do<br />
$ sudo pm-suspend<br />
have a look at {{ic|/var/log/pm-suspend.log}} and search for "ehci" or "xhci". Some of the names you could find may be "ehci_hd", "xhci_hd" or "ehci_hcd".<br />
<br />
Then as root create the file {{ic|/etc/pm/config.d/modules}} and include this code with the exact name of the ehci or xhci module you found. For example:<br />
SUSPEND_MODULES="ehci_hcd"<br />
Suspend should now be working.<br />
<br />
=== Blank screen issue ===<br />
Some users have reported having issues with their laptops not resuming after a suspend or hibernate. This is due to the {{ic|autodetect}} hook in "HOOKS" array of the {{ic|/etc/mkinitcpio.conf}} file. This can be disabled using the same method for adding the {{ic|resume}} hook. Just remove {{ic|autodetect}} from the list and follow the steps to build the new image. See [[Pm-utils#Mkinitcpio_Resume_Hook|Resume Hook]] for more details on building the new image.<br />
<br />
{{Note|If you are using [[Plymouth|plymouth]] it may be an other reason to this issue. Adding {{ic|resume}} before {{ic|plymouth}} in "HOOKS" array of the {{ic|/etc/mkinitcpio.conf}} file should fix this.}}<br />
<br />
=== Unable to Resume with 64 bit OS ===<br />
Certain motherboards/BIOS combinations (specifically known are some Zotac ITX boards, perhaps others) will not resume properly from suspend if any 64 bit operating system is installed. The solution is the enter your BIOS setup and Disable the "Memory Remapping Hole" in your DRAM configuration page. This will probably fix the suspend to RAM problem but will probably result in your OS not detecting all of your RAM. <br />
<br />
== Tips and Tricks ==<br />
<br />
=== Having the HD power management level automatically set again on resume ===<br />
Do it like this:<br />
{{hc|/etc/pm/sleep.d/50-hdparm_pm|<nowiki><br />
#!/bin/dash<br />
<br />
if [ -n "$1" ] && ([ "$1" = "resume" ] || [ "$1" = "thaw" ]); then<br />
hdparm -B 254 /dev/sda > /dev/null<br />
fi<br />
</nowiki>}}<br />
<br />
Then run:<br />
$ sudo chmod +x /etc/pm/sleep.d/50-hdparm_pm<br />
<br />
If the above [[Bash]] script fails the work, the following may work instead:<br />
{{hc|/etc/pm/sleep.d/50-hdparm_pm|<nowiki><br />
#!/bin/sh<br />
<br />
. "${PM_FUNCTIONS}"<br />
case "$1" in<br />
thaw|resume)<br />
sleep 6<br />
hdparm -B 254 /dev/sda<br />
;;<br />
*)<br />
;;<br />
esac<br />
exit $NA<br />
</nowiki>}}<br />
<br />
Lower {{ic|-B}} switch values may be effective. See [[hdparm]].<br />
<br />
=== Restarting the mouse ===<br />
On some laptops the mouse will hang after an otherwise successful suspend. One way to remedy this is to force a re-initialization of the PS/2 driver (here {{ic|i8042}}) through a hook in {{ic|/etc/pm/hooks}} (see [[#Creating_your_own_hooks|hooks]])<br />
<br />
#!/bin/sh<br />
echo -n "i8042" > /sys/bus/platform/drivers/i8042/unbind<br />
echo -n "i8042" > /sys/bus/platform/drivers/i8042/bind<br />
<br />
=== Add sleep modes to Openbox menu ===<br />
Openbox users can add the new scripts as additional shutdown options within the Openbox menu by adding the items to a new or existing sub-menu in {{ic|~/.config/openbox/menu.xml}}, for example:<br />
<menu id="64" label="Shutdown"><br />
<item label="Lock"> <action name="Execute"> <execute>xscreensaver-command -lock</execute> </action> </item><br />
<item label="Logout"> <action name="Exit"/> </item><br />
<item label="Reboot"> <action name="Execute"> <execute>sudo shutdown -r now</execute> </action> </item><br />
<item label="Poweroff"> <action name="Execute"> <execute>sudo shutdown -h now </execute> </action> </item><br />
'''<item label="Hibernate"> <action name="Execute"> <execute>sudo pm-hibernate</execute> </action> </item>'''<br />
'''<item label="Suspend"> <action name="Execute"> <execute>sudo pm-suspend</execute> </action> </item>'''<br />
</menu><br />
<br />
=== Handling "sleep" and "power" buttons ===<br />
"Sleep" and "power" buttons are handled by {{ic|acpid}} in {{ic|/etc/acpi/handler.sh}} (see "button/power" and "power/sleep" entries). You may want to substitute the default actions with calls to {{ic|pm-suspend}} and {{ic|pm-hibernate}}.<br />
<br />
=== Locking the screen saver on hibernate or suspend ===<br />
It is a good idea to have the system require a password after waking up. One way to do this is to make a script {{ic|/etc/pm/sleep.d/00screensaver-lock}} (making sure it is chmodded to 755 and owned by {{ic|root:root}}, like other similar scripts in this area). Replace '''username''' with your username and add your desired screen locker in between the "" after {{ic|su $USER -c}}.<br />
<br />
{{hc|/etc/pm/sleep.d/00screensaver-lock|<nowiki><br />
#!/bin/sh<br />
#<br />
# 00screensaver-lock: lock workstation on hibernate or suspend<br />
<br />
DBUS=$(ps aux | grep 'dbus-launch' | grep -v root)<br />
if [[ ! -z $DBUS ]];then<br />
USER=$(echo $DBUS | awk '{print $1}')<br />
USERHOME=$(getent passwd $USER | cut -d: -f6)<br />
export XAUTHORITY="$USERHOME/.Xauthority"<br />
for x in /tmp/.X11-unix/*; do<br />
DISPLAYNUM=$(echo $x | sed s#/tmp/.X11-unix/X##)<br />
if [[ -f "$XAUTHORITY" ]]; then<br />
export DISPLAY=":$DISPLAYNUM"<br />
fi<br />
done<br />
else<br />
USER=username<br />
USERHOME=/home/username<br />
export XAUTHORITY="$USERHOME/.Xauthority"<br />
export DISPLAY=":0"<br />
fi<br />
<br />
case "$1" in<br />
hibernate|suspend)<br />
su $USER -c "/usr/bin/slimlock" & # or any other such as /usr/bin/xscreensaver-command -lock<br />
;;<br />
thaw|resume)<br />
;;<br />
*) exit $NA<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
'''Note:''' for the previous script to work TTY lock must be disabled in slimlock. Be sure to set {{ic|tty_lock 0}} in {{ic|/etc/slimlock.conf}} [https://github.com/joelburget/slimlock/issues/4].<br />
<br />
For some the above script might not work, use this one instead:<br />
<br />
{{hc|/etc/pm/sleep.d/00screensaver-lock|<nowiki><br />
#!/bin/sh<br />
#<br />
# 00screensaver-lock: lock workstation on hibernate or suspend<br />
<br />
username= # add your username here, i.e.: username=foobar<br />
<br />
USERHOME=/home/$username<br />
export XAUTHORITY="$USERHOME/.Xauthority"<br />
export DISPLAY=":0"<br />
<br />
case "$1" in<br />
hibernate|suspend)<br />
su $username -c "/usr/bin/slimlock" & # or any other such as /usr/bin/xscreensaver-command -lock<br />
;;<br />
thaw|resume)<br />
;;<br />
*) exit $NA<br />
;;<br />
esac<br />
<br />
<br />
</nowiki>}}<br />
<br />
A simple method (possibly incorrect) is running the locker in background ans pm-suspend in the foreground<br />
<br />
coproc slock && pm-suspend<br />
<br />
== Other Resources ==<br />
* [https://wiki.ubuntu.com/UnderstandingSuspend Understanding Suspend] - Ubuntu article explaining how suspending to RAM works<br />
* [http://www.mjmwired.net/kernel/Documentation/power/basic-pm-debugging.txt#178 PM Debugging] - Basic PM debugging<br />
*[[Cpufrequtils]] - CPU Frequency Scaling and CPU Power schemes<br />
*[[Acpid]] - daemon for delivering ACPI events<br />
* [http://superuser.com/questions/298672/linuxhow-to-hibernate-after-a-period-of-sleep Hibernate after sleep] - An example of a custom pm-utils hook where hibernation is triggered after a period of time in suspension<br />
<br />
== Credits ==<br />
''This wiki entry was originally sourced from the [http://en.opensuse.org/SDB:Pm-utils OpenSUSE Wiki] (Licensed under GPL). A big thank you goes to the {{Pkg|pm-utils}} developers and documenters for their time.''</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Ruby_on_Rails&diff=231403Ruby on Rails2012-10-25T07:57:59Z<p>Lfxgroove: Added some info on how to do it without subdomains</p>
<hr />
<div>[[Category:Web Server]]<br />
[[zh-CN:Ruby on Rails]]<br />
[http://rubyonrails.org/ Ruby on Rails], often shortened to Rails or RoR, is an open source web application framework for the Ruby programming language. It is intended to be used with an Agile development methodology that is used by web developers for rapid development.<br />
<br />
This document describes how to set up the Ruby on Rails Framework on an Arch Linux system.<br />
<br />
Ruby on Rails requires [[Ruby]] to be installed, so read that article first for installation instructions.<br />
<br />
== Option A: Installation via RubyGems (Recommended) ==<br />
<br />
{{Box Note | If this command is run without being root (using sudo or otherwise), the gem will be installed into the home directory of the user.}}<br />
<br />
# gem install rails<br />
<br />
Building the documentation takes a while. If you want to skip it, append the parameters --no-ri --no-rdoc to the install command.<br />
# gem install rails --no-ri --no-rdoc<br />
<br />
=== Updating Gems ===<br />
<br />
gem is a package manager for Ruby modules, somewhat like pacman is to Arch Linux. To update your gems, simply run:<br />
# gem update<br />
<br />
== Option B: Installing via the AUR ==<br />
<br />
{{Warning|This is not recommended, as this might not include the latest Rails version, and additional dependencies may be introduced that may require you to run {{Ic|gem install}} anyway.}}<br />
There is a {{AUR|rails}} package available in the [[AUR]]. Note that this is not in an [[Official Repositories|official repository]], so you will need to [[AUR#Build_the_package|build it manually]].<br />
<br />
== Configuration ==<br />
<br />
Rails is bundled with a basic HTTP server called WeBrick. You can create a test application to test it. First, create an application with the rails command:<br />
<br />
$ rails new testapp_name<br />
<br />
This makes a new folder in your current working directory. Next start the web server. It listens on port 3000 by default:<br />
<br />
$ cd testapp_name<br />
$ rails server<br />
<br />
Finally open your server address on port 3000 in your web browser. For example, if you are working on your local machine, visit http://localhost:3000.<br />
<br />
A test-page should shown greeting you "Welcome aboard".<br />
<br />
== Application servers ==<br />
<br />
While the default Ruby On Rails HTTP server (WeBrick) is convenient for basic development it is not recommended for production use. Generally, you should choose between installing the Phusion Passenger module for your webserver ([[Apache]] or [[Nginx]]), or use a dedicated application-server (such as Mongrel or Unicorn) combined with a separate web-server acting as a reverse proxy.<br />
<br />
=== Mongrel ===<br />
Mongrel is a drop-in replacement for WeBrick, that can be run in precisely the same way, but offers better performance.<br />
<br />
First install the Mongrel gem:<br />
# gem install mongrel<br />
<br />
Then start it using:<br />
# mongrel_rails start<br />
<br />
Alternatively, you can just run "ruby script/server" again, as it replaces WeBrick by default.<br />
<br />
=== Unicorn ===<br />
[http://unicorn.bogomips.org/ Unicorn] is loosely based on Mongrel, and is used by Github. It uses a different architecture that tries harder to find the best child for handling a request. [https://github.com/blog/517-unicorn Explanation of differences between Unicorn and Mongrel].<br />
<br />
Install the Unicorn gem:<br />
# gem install unicorn<br />
<br />
Then create a configuration file for your application in /etc/unicorn/. For example; here is a configuration example (Based on [http://www.warden.pl/2011/01/07/running-redmine-under-unicorn-in-debian/]) for Redmine:<br />
<br />
<pre>working_directory "/srv/http/redmine"<br />
pid "/tmp/redmine.pid"<br />
<br />
preload_app true<br />
timeout 60<br />
worker_processes 4<br />
listen 4000<br />
stderr_path('/var/log/unicorn.log')<br />
<br />
GC.respond_to?(:copy_on_write_friendly=) and GC.copy_on_write_friendly = true<br />
<br />
after_fork do |server, worker|<br />
#start the worker on port 4000, 4001, 4002 etc...<br />
addr = "0.0.0.0:#{4000 + worker.nr}"<br />
# infinite tries to start the worker<br />
server.listen(addr, :tries => -1, :delay => -1, :backlog => 128)<br />
<br />
#Drop privileges if running as root<br />
worker.user('nobody', 'nobody') if Process.euid == 0<br />
end</pre><br />
<br />
Start it using:<br />
# usr/bin/unicorn -D -E production -c /etc/unicorn/redmine.ru<br />
<br />
=== Apache/Nginx (using Phusion Passenger) ===<br />
<br />
[http://www.modrails.com/ Passenger] also known as {{ic|mod_rails}} is a module available for [[Nginx]] and [[Apache]], that greatly simplifies setting up a Rails server environment. Nginx does not support modules as Apache and has to be compiled with {{ic|mod_rails}} in order to support Passenger; let Passenger compile it for you. As for Apache, let Passenger set up the module for you.<br />
<br />
{{note|The current Nginx package in the official repositories actually is compiled with the Passenger module, so you can install it via pacman. The configuration files are stored in {{ic|/etc/nginx/conf/}}.}}<br />
<br />
Start by installing the 'passenger' gem:<br />
# gem install passenger<br />
<br />
If you are aiming to use [[Apache]], run:<br />
# passenger-install-apache2-module<br />
<br />
For [[Nginx]]:<br />
# passenger-install-nginx-module<br />
<br />
The installer will provide you with any additional information regarding the installation (such as installing additional libraries).<br />
<br />
To serve an application with Nginx, configure it as follows:<br />
<pre><br />
server {<br />
server_name app.example.org;<br />
root path_to_app/public; # Be sure to point to 'public' folder!<br />
passenger_enabled on;<br />
rails_env development; # Rails environment.<br />
}<br />
</pre><br />
<br />
== Databases ==<br />
<br />
Most web applications will need to interact with some sort of database. ActiveRecord (the ORM used by Rails to provide database abstraction) supports several database vendors, the most popular of which are MySQL, SQLite, and PostgreSQL.<br />
<br />
=== SQLite ===<br />
<br />
SQLite is the default lightweight database for Ruby on Rails. To enable SQLite, simply install {{Pkg|sqlite3}}.<br />
<br />
=== PostgreSQL ===<br />
<br />
(Stub.)<br />
<br />
Install {{Pkg|postgresql}}.<br />
<br />
=== MySQL ===<br />
<br />
{{Note|You must first install [[MySQL]] with the appropriate headers in {{ic|/usr/include}} (just installing {{Pkg|mysql}} is fine) before attempting to install the Ruby MySQL extensions.}}<br />
<br />
Please refer to [[MySQL]] on how to install MySQL Server.<br />
<br />
A gem with some native extensions is required, probably best installed as root:<br />
# sudo gem install mysql<br />
<br />
You can generate a rails application configured for MySQL by using the {{Ic|-d}} parameter:<br />
$ rails new testapp_name -d mysql<br />
<br />
You then need to edit config/database.yml. Rails uses different databases for development, testing, production and other environments. Here is an example development configuration for MySQL running on localhost:<br />
<br />
development:<br />
adapter: mysql<br />
database: my_application_database<br />
username: development<br />
password: my_secret_password<br />
<br />
Note that you do not have to actually create the database using MySQL, as this can be done via Rails with:<br />
# rake db:create<br />
<br />
If no errors are shown, then your database has been created and Rails can talk to your MySQL database.<br />
<br />
== Option C: The Perfect Rails Setup ==<br />
<br />
''Phusion Passenger running multiple Ruby versions.''<br />
<br />
* [http://www.archlinux.org/ Archlinux]: A simple, lightweight distribution. ;)<br />
* [http://www.nginx.org/ Nginx]: A fast and lightweight '''web server''' with a strong focus on high concurrency, performance and low memory usage.<br />
* [http://www.modrails.com/ Passenger] (a.k.a. mod_rails or mod_rack): Supports both Apache and Nginx web servers. It makes deployment of Ruby web applications, such as those built on Ruby on Rails web framework, a breeze.<br />
* [http://www.rubyenterpriseedition.com/ Ruby Enterprise Edition] (REE): Passenger allows Ruby on Rails applications to use about 33% less memory, when used in combination with REE.<br />
* [http://rvm.beginrescueend.com/ Ruby Version Manager] (RVM): A command-line tool which allows you to easily install, manage, and work with multiple Ruby environments from interpreters to sets of gems. RVM lets you deploy each project with its own completely self-contained and dedicated environment —from the specific version of ruby, all the way down to the precise set of required gems to run your application—.<br />
* [http://sqlite.org/ SQLite]: The default lightweight '''database''' for Ruby on Rails.<br />
<br />
=== Step 0: SQLite ===<br />
<br />
Easy as:<br />
$ sudo pacman -S sqlite<br />
<br />
{{note|Of course SQLite is not critical in this setup, you can use MySQL and PostgreSQL as well.}}<br />
<br />
=== Step 1: RVM ===<br />
<br />
Make a multi-user [[RVM]] installation as specified [[RVM#Multi-user_installation|here]].<br />
<br />
In the 'adding users to the rvm group' step, do<br />
$ sudo usermod -a -G rvm http<br />
$ sudo usermod -a -G rvm nobody<br />
. http and nobody are the users related to Nginx and Passenger, respectively.<br />
<br />
{{note|Maybe adding the 'nobody' user to the 'rvm' group is not necessary.}}<br />
<br />
=== Step 2: Rubies ===<br />
<br />
Once you have a working RVM installation in your hands, it is time to install the Ruby Enterprise Edition interpreter<br />
{{Note|During the installation of Ruby Enterprise Edition patches will be applied. Consider installing '''base-devel''' beforehand.}}<br />
<br />
$ rvm install ree<br />
. Also take the chance to include other interpreters you want to use, like the last Ruby version<br />
$ rvm install 1.9.3<br />
<br />
==== Advice ====<br />
<br />
I have found useful to delete the 'global' gemsets of the environments that have web applications. Their gems were somehow interfering with Passenger. Do not do<br />
$ rvm ree do gemset delete global<br />
$ rvm 1.9.3 do gemset delete global<br />
now, but consider this later if you encounter complications.<br />
<br />
=== Step 3: Nginx with Passenger support ===<br />
<br />
Do not install Nginx via pacman. This web server does not support modules as Apache, so it must be compiled from source with the functionality of ''mod_rails'' (Passenger). Fortunately this is straightforward thanks to the passenger gem. Get it:<br />
$ rvm use ree<br />
$ gem install passenger<br />
. The gem will be put into the 'default' gemset. Now execute the following script:<br />
<br />
{{note|The current nginx package in the official repos actually was compiled with the passenger module. So you can install it via pacman and skip this step. The config files are stored in /etc/nginx/conf/. }}<br />
<br />
$ rvmsudo passenger-install-nginx-module<br />
. It will download the sources of Nginx, compile and install it for you. It will guide you through all the process. (The default location for Nginx is /opt/nginx.)<br />
<br />
{{note|If you encounter a compilation error regarding Boost threads, see [http://bbs.archlinux.org/viewtopic.php?id&#61;139164 this] article.}}<br />
<br />
After completion, the script will require you to add two lines into the 'http block' at {{ic|/opt/nginx/conf/nginx.conf}} that look like:<br />
http { <br />
...<br />
passenger_root /usr/local/rvm/gems/ree-1.8.7-2011.03/gems/passenger-3.0.9;<br />
passenger_ruby /usr/local/rvm/wrappers/ree-1.8.7-2011.03/ruby;<br />
...<br />
}<br />
<br />
If you installed [[Nginx]] from pacman the {{ic|passenger_root}} needs to be changed to:<br />
passenger_root /usr/lib/passenger/;<br />
{{warning|Do not set it to {{ic|/usr/lib/passenger/bin/passenger}} since this will result in [[Nginx]] segfaulting when checking the config}}<br />
<br />
For everything that is not Ruby, use [[Nginx]] as usual to serve static pages, PHP and Python. Check the wiki page for more information.<br />
<br />
To enable the Nnginx service by default at start-up just add {{Ic|nginx}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:<br />
DAEMONS=(ntpd syslog-ng ... nginx)<br />
<br />
{{note|It is possible that your Nginx installation has not come with an init script; check your /etc/rc.d/ directory for a file called ''nginx'', if that is your case manually create it. Help yourself with [[Nginx/Init_script]]. If you installed nginx to another location, such as /opt/nginx, you will need to edit the init script accordingly.}}<br />
<br />
=== Step 4: Gemsets and Apps ===<br />
<br />
For each Rails application you should have a gemset. Suppose that you want to try [http://refinerycms.com RefineryCMS] against [http://www.browsercms.org BrowserCMS], two open-source Content Management Systems based on Rails. Then you should do:<br />
$ rvm use ree@refinery --create<br />
$ gem install rails -v 3.0.11<br />
$ gem install passenger<br />
$ gem install refinerycms refinerycms-i18n sqlite3<br />
Deploy a RefineryCMS instance called ''refineria'':<br />
$ cd /srv/http/<br />
$ rvmsudo refinerycms refineria<br />
Again:<br />
$ rvm use 1.9.3@browser --create<br />
$ gem install passenger<br />
$ gem install browsercms sqlite3<br />
Deploy a BrowserCMS instance called ''navegador'':<br />
$ cd /srv/http/<br />
$ rvmsudo browsercms demo navegador<br />
$ cd /srv/http/navegador<br />
$ rvmsudo rake db:install<br />
<br />
=== Passenger for Nginx and Passenger Standalone ===<br />
<br />
Observe that the passenger gem was installed three times and with different intentions; in the environments<br />
* ''ree'' => for Nginx,<br />
* ''ree@refinery'' => Standalone, and<br />
* ''1.9.3@browser'' => Standalone.<br />
<br />
The strategy is to combine Passenger for Nginx with Passenger Standalone. One must first identify the Ruby environment (interpreter plus gemset) that one uses the most; in this setup the REE interpreter and the default gemset were selected. One then proceeds with setting up Passenger for Nginx to use that environment (step 3).<br />
* Applications within the chosen environment can be served as in [[Ruby_on_Rails#Apache.2FNginx_.28using_Phusion_Passenger.29|Apache/Nginx (using Phusion Passenger)]], page up in this article.<br />
* All applications that are to use a different Ruby version and/or gemset can be served separately through Passenger Standalone and hook into the main web server via a reverse proxy configuration (step 6).<br />
<br />
=== Step 5: .rvmrc files and ownerships ===<br />
<br />
This step is crucial for the correct behaviour of the setup. RVM seeks for .rvmrc files when changing folders; if it finds one, it reads it. In these files normally one stores a line like<br />
rvm <ruby_version>@<gemset_name><br />
so the specified environment is set at the entrance of applications' root folder.<br />
<br />
Create /srv/http/refineria/.rvmrc doing<br />
sudo sh -c 'echo "rvm ree@refinery" > /srv/http/refineria/.rvmrc'<br />
, and /srv/http/navegador/.rvmrc with<br />
sudo sh -c 'echo "rvm 1.9.3@browser" > /srv/http/navegador/.rvmrc'<br />
You have to enter to both application root folders now, because every first time that RVM finds a .rvmrc it asks you if you trust the given file, consequently you must validate the two files you have just created.<br />
<br />
These files aid the programs involved to find the correct gems.<br />
<br />
Apart, if applications' files and folders are not owned by the right user you will face database write-access problems. The use of rvmsudo produces ''root''-owned archives when generated by Rails; in the other hand, ''nobody'' is the user for Passenger —if you have not changed it—: who will use and should posses them. Fix this doing<br />
$ sudo chown -R nobody.nobody /srv/http/refineria /srv/http/navegador<br />
<br />
=== Step 6: Reverse proxies ===<br />
<br />
You have to start the Passenger Standalone web servers for your applications. So, do<br />
$ cd /srv/http/refineria<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
and<br />
$ cd /srv/http/navegador<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
. The first time that you run a Passenger Standalone it will perform a minor installation.<br />
<br />
Note that you are using ''unix domain'' sockets instead of the commonly-used ''TCP'' sockets; it turns out that unix domain are significantly faster than TCP sockets.<br />
<br />
{{note|If you are experimenting trouble with unix sockets, changing to TCP should work:<br />
rvmsudo passenger start -a 127.0.0.1 -p 3000 -d<br />
}}<br />
<br />
==== Launch Passenger Standalone daemons at system start-up ====<br />
<br />
''Do you have a script? Please post it here.''<br />
<br />
The systemd script below was made for a Typo blog I host at /srv/http/typo. It's located at /etc/systemd/system/passenger_typo.service. I set the Environment= tags (see "man systemd.exec") from the output of "rvm env". The only exception was PATH=, which I had to combine from my regular PATH and the output of rvm env.<br />
<br />
Note: If you don't set the "WorkingDirectory=" variable to your application folder, passenger will fail to find your app and will subsequently shut itself down.<br />
<br />
<pre><br />
[Unit]<br />
Description=Passenger Standalone Script for Typo<br />
After=network.target<br />
<br />
[Service]<br />
Type=forking<br />
WorkingDirectory=/srv/http/typo<br />
PIDFile=/srv/http/typo/tmp/pids/passenger.pid<br />
<br />
Environment=PATH=/usr/local/rvm/gems/ruby-1.9.3-p194@typo/bin:/usr/local/rvm/gems/ruby-1.9.3-p194@global/bin:/usr/local/rvm/rubies/ruby-1.9.3-p194/bin:/usr/local/rvm/bin:/usr/local/bin:/usr/bin:/bin:/usr/local/sbin:/usr/sbin:/sbin:/usr/bin/core_perl<br />
Environment=rvm_env_string=ruby-1.9.3-p194@typo<br />
Environment=rvm_path=/usr/local/rvm<br />
Environment=rvm_ruby_string=ruby-1.9.3-p194<br />
Environment=rvm_gemset_name=typo<br />
Environment=RUBY_VERSION=ruby-1.9.3-p194<br />
Environment=GEM_HOME=/usr/local/rvm/gems/ruby-1.9.3-p194@typo<br />
Environment=GEM_PATH=/usr/local/rvm/gems/ruby-1.9.3-p194@typo:/usr/local/rvm/gems/ruby-1.9.3-p194@global<br />
Environment=MY_RUBY_HOME=/usr/local/rvm/rubies/ruby-1.9.3-p194<br />
Environment=IRBRC=/usr/local/rvm/rubies/ruby-1.9.3-p194/.irbrc<br />
<br />
ExecStart=/bin/bash -c "rvmsudo passenger start --socket /srv/http/typo/tmp/sockets/passenger.socket -d"<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</pre><br />
<br />
=== Step 7: Deployment ===<br />
<br />
== With subdomains ==<br />
<br />
Once again edit /opt/nginx/conf/nginx.conf to include some vital instructions:<br />
<br />
<pre><br />
## RefineryCMS ##<br />
<br />
server {<br />
server_name refinery.domain.com;<br />
root /srv/http/refineria/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/refineria/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
<br />
## BrowserCMS ##<br />
<br />
server {<br />
server_name browser.domain.com;<br />
root /srv/http/navegador/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/navegador/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
{{note|Or if using TCP sockets, configure the ''proxy_pass'' directive like<br />
<pre>proxy_pass http://127.0.0.1:3000;</pre><br />
}}<br />
<br />
== Without subdomains ==<br />
<br />
If you for some reason don't want to host each application on it's own subdomain but rather in a url like: {{ic|site.com/railsapp}} then you could do something like this in your config:<br />
<br />
<pre><br />
server {<br />
server_name site.com;<br />
#Base for the html files etc<br />
root /srv/http/;<br />
<br />
#First application you want hosted under domain site.com/railsapp<br />
location /railsapp {<br />
root /srv/http/railsapp/public;<br />
#you may need to change passenger_base_uri to be the uri you want to point at, ie:<br />
#passenger_base_uri /railsapp;<br />
#but probably only if you're using the other solution with passenger phusion<br />
proxy_pass http://unix:/srv/http/railsapp/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
<br />
#Second applicatino you want hosted under domain site.com/anotherapp<br />
location /anotherapp {<br />
root /srv/http/anotherapp/public;<br />
#same thing about the passenger_base_uri here, but with value /anotherapp instead<br />
proxy_pass http://unix:/srv/http/anotherapp/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
At this point you are in conditions to run Nginx with:<br />
<br />
$ sudo rc.d start nginx<br />
<br />
and to access both CMSs through ''refinery.domain.com'' and ''browser.domain.com''.<br />
<br />
=== References ===<br />
<br />
* http://beginrescueend.com/integration/passenger<br />
* http://blog.phusion.nl/2010/09/21/phusion-passenger-running-multiple-ruby-versions<br />
<br />
== See also ==<br />
<br />
* [[Ruby]]<br />
* [[Nginx]]<br />
* [[LAMP]]<br />
* [[MySQL]]<br />
<br />
== References ==<br />
<br />
* Ruby on Rails http://rubyonrails.org/download.<br />
* Mongrel http://mongrel.rubyforge.org.</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Ruby_on_Rails&diff=229422Ruby on Rails2012-10-18T12:32:41Z<p>Lfxgroove: /* Step 3: Nginx with Passenger support */ add notice for users installing with pacman</p>
<hr />
<div>[[Category:Web Server]]<br />
[[zh-CN:Ruby on Rails]]<br />
[http://rubyonrails.org/ Ruby on Rails], often shortened to Rails or RoR, is an open source web application framework for the Ruby programming language. It is intended to be used with an Agile development methodology that is used by web developers for rapid development.<br />
<br />
This document describes how to set up the Ruby on Rails Framework on an Arch Linux system.<br />
<br />
Ruby on Rails requires [[Ruby]] to be installed, so read that article first for installation instructions.<br />
<br />
== Option A: Installation via RubyGems (Recommended) ==<br />
<br />
{{Box Note | If this command is run without being root (using sudo or otherwise), the gem will be installed into the home directory of the user.}}<br />
<br />
# gem install rails<br />
<br />
Building the documentation takes a while. If you want to skip it, append the parameters --no-ri --no-rdoc to the install command.<br />
# gem install rails --no-ri --no-rdoc<br />
<br />
=== Updating Gems ===<br />
<br />
gem is a package manager for Ruby modules, somewhat like pacman is to Arch Linux. To update your gems, simply run:<br />
# gem update<br />
<br />
== Option B: Installing via the AUR ==<br />
<br />
{{Warning|This is not recommended, as this might not include the latest Rails version, and additional dependencies may be introduced that may require you to run {{Ic|gem install}} anyway.}}<br />
There is a {{AUR|rails}} package available in the [[AUR]]. Note that this is not in an [[Official Repositories|official repository]], so you will need to [[AUR#Build_the_package|build it manually]].<br />
<br />
== Configuration ==<br />
<br />
Rails is bundled with a basic HTTP server called WeBrick. You can create a test application to test it. First, create an application with the rails command:<br />
<br />
$ rails new testapp_name<br />
<br />
This makes a new folder in your current working directory. Next start the web server. It listens on port 3000 by default:<br />
<br />
$ cd testapp_name<br />
$ rails server<br />
<br />
Finally open your server address on port 3000 in your web browser. For example, if you are working on your local machine, visit http://localhost:3000.<br />
<br />
A test-page should shown greeting you "Welcome aboard".<br />
<br />
== Application servers ==<br />
<br />
While the default Ruby On Rails HTTP server (WeBrick) is convenient for basic development it is not recommended for production use. Generally, you should choose between installing the Phusion Passenger module for your webserver ([[Apache]] or [[Nginx]]), or use a dedicated application-server (such as Mongrel or Unicorn) combined with a separate web-server acting as a reverse proxy.<br />
<br />
=== Mongrel ===<br />
Mongrel is a drop-in replacement for WeBrick, that can be run in precisely the same way, but offers better performance.<br />
<br />
First install the Mongrel gem:<br />
# gem install mongrel<br />
<br />
Then start it using:<br />
# mongrel_rails start<br />
<br />
Alternatively, you can just run "ruby script/server" again, as it replaces WeBrick by default.<br />
<br />
=== Unicorn ===<br />
[http://unicorn.bogomips.org/ Unicorn] is loosely based on Mongrel, and is used by Github. It uses a different architecture that tries harder to find the best child for handling a request. [https://github.com/blog/517-unicorn Explanation of differences between Unicorn and Mongrel].<br />
<br />
Install the Unicorn gem:<br />
# gem install unicorn<br />
<br />
Then create a configuration file for your application in /etc/unicorn/. For example; here is a configuration example (Based on [http://www.warden.pl/2011/01/07/running-redmine-under-unicorn-in-debian/]) for Redmine:<br />
<br />
<pre>working_directory "/srv/http/redmine"<br />
pid "/tmp/redmine.pid"<br />
<br />
preload_app true<br />
timeout 60<br />
worker_processes 4<br />
listen 4000<br />
stderr_path('/var/log/unicorn.log')<br />
<br />
GC.respond_to?(:copy_on_write_friendly=) and GC.copy_on_write_friendly = true<br />
<br />
after_fork do |server, worker|<br />
#start the worker on port 4000, 4001, 4002 etc...<br />
addr = "0.0.0.0:#{4000 + worker.nr}"<br />
# infinite tries to start the worker<br />
server.listen(addr, :tries => -1, :delay => -1, :backlog => 128)<br />
<br />
#Drop privileges if running as root<br />
worker.user('nobody', 'nobody') if Process.euid == 0<br />
end</pre><br />
<br />
Start it using:<br />
# usr/bin/unicorn -D -E production -c /etc/unicorn/redmine.ru<br />
<br />
=== Apache/Nginx (using Phusion Passenger) ===<br />
<br />
[http://www.modrails.com/ Passenger] also known as {{ic|mod_rails}} is a module available for [[Nginx]] and [[Apache]], that greatly simplifies setting up a Rails server environment. Nginx does not support modules as Apache and has to be compiled with {{ic|mod_rails}} in order to support Passenger; let Passenger compile it for you. As for Apache, let Passenger set up the module for you.<br />
<br />
{{note|The current Nginx package in the official repositories actually is compiled with the Passenger module, so you can install it via pacman. The configuration files are stored in {{ic|/etc/nginx/conf/}}.}}<br />
<br />
Start by installing the 'passenger' gem:<br />
# gem install passenger<br />
<br />
If you are aiming to use [[Apache]], run:<br />
# passenger-install-apache2-module<br />
<br />
For [[Nginx]]:<br />
# passenger-install-nginx-module<br />
<br />
The installer will provide you with any additional information regarding the installation (such as installing additional libraries).<br />
<br />
To serve an application with Nginx, configure it as follows:<br />
<pre><br />
server {<br />
server_name app.example.org;<br />
root path_to_app/public; # Be sure to point to 'public' folder!<br />
passenger_enabled on;<br />
rails_env development; # Rails environment.<br />
}<br />
</pre><br />
<br />
== Databases ==<br />
<br />
Most web applications will need to interact with some sort of database. ActiveRecord (the ORM used by Rails to provide database abstraction) supports several database vendors, the most popular of which are MySQL, SQLite, and PostgreSQL.<br />
<br />
=== SQLite ===<br />
<br />
SQLite is the default lightweight database for Ruby on Rails. To enable SQLite, simply install {{Pkg|sqlite3}}.<br />
<br />
=== PostgreSQL ===<br />
<br />
(Stub.)<br />
<br />
Install {{Pkg|postgresql}}.<br />
<br />
=== MySQL ===<br />
<br />
{{Note|You must first install [[MySQL]] with the appropriate headers in {{ic|/usr/include}} (just installing {{Pkg|mysql}} is fine) before attempting to install the Ruby MySQL extensions.}}<br />
<br />
Please refer to [[MySQL]] on how to install MySQL Server.<br />
<br />
A gem with some native extensions is required, probably best installed as root:<br />
# sudo gem install mysql<br />
<br />
You can generate a rails application configured for MySQL by using the {{Ic|-d}} parameter:<br />
$ rails new testapp_name -d mysql<br />
<br />
You then need to edit config/database.yml. Rails uses different databases for development, testing, production and other environments. Here is an example development configuration for MySQL running on localhost:<br />
<br />
development:<br />
adapter: mysql<br />
database: my_application_database<br />
username: development<br />
password: my_secret_password<br />
<br />
Note that you do not have to actually create the database using MySQL, as this can be done via Rails with:<br />
# rake db:create<br />
<br />
If no errors are shown, then your database has been created and Rails can talk to your MySQL database.<br />
<br />
== Option C: The Perfect Rails Setup ==<br />
<br />
''Phusion Passenger running multiple Ruby versions.''<br />
<br />
* [http://www.archlinux.org/ Archlinux]: A simple, lightweight distribution. ;)<br />
* [http://www.nginx.org/ Nginx]: A fast and lightweight '''web server''' with a strong focus on high concurrency, performance and low memory usage.<br />
* [http://www.modrails.com/ Passenger] (a.k.a. mod_rails or mod_rack): Supports both Apache and Nginx web servers. It makes deployment of Ruby web applications, such as those built on Ruby on Rails web framework, a breeze.<br />
* [http://www.rubyenterpriseedition.com/ Ruby Enterprise Edition] (REE): Passenger allows Ruby on Rails applications to use about 33% less memory, when used in combination with REE.<br />
* [http://rvm.beginrescueend.com/ Ruby Version Manager] (RVM): A command-line tool which allows you to easily install, manage, and work with multiple Ruby environments from interpreters to sets of gems. RVM lets you deploy each project with its own completely self-contained and dedicated environment —from the specific version of ruby, all the way down to the precise set of required gems to run your application—.<br />
* [http://sqlite.org/ SQLite]: The default lightweight '''database''' for Ruby on Rails.<br />
<br />
=== Step 0: SQLite ===<br />
<br />
Easy as:<br />
$ sudo pacman -S sqlite<br />
<br />
{{note|Of course SQLite is not critical in this setup, you can use MySQL and PostgreSQL as well.}}<br />
<br />
=== Step 1: RVM ===<br />
<br />
Make a multi-user [[RVM]] installation as specified [[RVM#Multi-user_installation|here]].<br />
<br />
In the 'adding users to the rvm group' step, do<br />
$ sudo usermod -a -G rvm http<br />
$ sudo usermod -a -G rvm nobody<br />
. http and nobody are the users related to Nginx and Passenger, respectively.<br />
<br />
{{note|Maybe adding the 'nobody' user to the 'rvm' group is not necessary.}}<br />
<br />
=== Step 2: Rubies ===<br />
<br />
Once you have a working RVM installation in your hands, it is time to install the Ruby Enterprise Edition interpreter<br />
{{Note|During the installation of Ruby Enterprise Edition patches will be applied. Consider installing '''base-devel''' beforehand.}}<br />
<br />
$ rvm install ree<br />
. Also take the chance to include other interpreters you want to use, like the last Ruby version<br />
$ rvm install 1.9.3<br />
<br />
==== Advice ====<br />
<br />
I have found useful to delete the 'global' gemsets of the environments that have web applications. Their gems were somehow interfering with Passenger. Do not do<br />
$ rvm ree do gemset delete global<br />
$ rvm 1.9.3 do gemset delete global<br />
now, but consider this later if you encounter complications.<br />
<br />
=== Step 3: Nginx with Passenger support ===<br />
<br />
Do not install Nginx via pacman. This web server does not support modules as Apache, so it must be compiled from source with the functionality of ''mod_rails'' (Passenger). Fortunately this is straightforward thanks to the passenger gem. Get it:<br />
$ rvm use ree<br />
$ gem install passenger<br />
. The gem will be put into the 'default' gemset. Now execute the following script:<br />
<br />
{{note|The current nginx package in the official repos actually was compiled with the passenger module. So you can install it via pacman and skip this step. The config files are stored in /etc/nginx/conf/. }}<br />
<br />
$ rvmsudo passenger-install-nginx-module<br />
. It will download the sources of Nginx, compile and install it for you. It will guide you through all the process. (The default location for Nginx is /opt/nginx.)<br />
<br />
{{note|If you encounter a compilation error regarding Boost threads, see [http://bbs.archlinux.org/viewtopic.php?id&#61;139164 this] article.}}<br />
<br />
After completion, the script will require you to add two lines into the 'http block' at {{ic|/opt/nginx/conf/nginx.conf}} that look like:<br />
http { <br />
...<br />
passenger_root /usr/local/rvm/gems/ree-1.8.7-2011.03/gems/passenger-3.0.9;<br />
passenger_ruby /usr/local/rvm/wrappers/ree-1.8.7-2011.03/ruby;<br />
...<br />
}<br />
<br />
If you installed [[Nginx]] from pacman the {{ic|passenger_root}} needs to be changed to:<br />
passenger_root /usr/lib/passenger/;<br />
{{warning|Do not set it to {{ic|/usr/lib/passenger/bin/passenger}} since this will result in [[Nginx]] segfaulting when checking the config}}<br />
<br />
For everything that is not Ruby, use [[Nginx]] as usual to serve static pages, PHP and Python. Check the wiki page for more information.<br />
<br />
To enable the Nnginx service by default at start-up just add {{Ic|nginx}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:<br />
DAEMONS=(ntpd syslog-ng ... nginx)<br />
<br />
{{note|It is possible that your Nginx installation has not come with an init script; check your /etc/rc.d/ directory for a file called ''nginx'', if that is your case manually create it. Help yourself with [[Nginx/Init_script]]. If you installed nginx to another location, such as /opt/nginx, you will need to edit the init script accordingly.}}<br />
<br />
=== Step 4: Gemsets and Apps ===<br />
<br />
For each Rails application you should have a gemset. Suppose that you want to try [http://refinerycms.com RefineryCMS] against [http://www.browsercms.org BrowserCMS], two open-source Content Management Systems based on Rails. Then you should do:<br />
$ rvm use ree@refinery --create<br />
$ gem install rails -v 3.0.11<br />
$ gem install passenger<br />
$ gem install refinerycms refinerycms-i18n sqlite3<br />
Deploy a RefineryCMS instance called ''refineria'':<br />
$ cd /srv/http/<br />
$ rvmsudo refinerycms refineria<br />
Again:<br />
$ rvm use 1.9.3@browser --create<br />
$ gem install passenger<br />
$ gem install browsercms sqlite3<br />
Deploy a BrowserCMS instance called ''navegador'':<br />
$ cd /srv/http/<br />
$ rvmsudo browsercms demo navegador<br />
$ cd /srv/http/navegador<br />
$ rvmsudo rake db:install<br />
<br />
=== Passenger for Nginx and Passenger Standalone ===<br />
<br />
Observe that the passenger gem was installed three times and with different intentions; in the environments<br />
* ''ree'' => for Nginx,<br />
* ''ree@refinery'' => Standalone, and<br />
* ''1.9.3@browser'' => Standalone.<br />
<br />
The strategy is to combine Passenger for Nginx with Passenger Standalone. One must first identify the Ruby environment (interpreter plus gemset) that one uses the most; in this setup the REE interpreter and the default gemset were selected. One then proceeds with setting up Passenger for Nginx to use that environment (step 3).<br />
* Applications within the chosen environment can be served as in [[Ruby_on_Rails#Apache.2FNginx_.28using_Phusion_Passenger.29|Apache/Nginx (using Phusion Passenger)]], page up in this article.<br />
* All applications that are to use a different Ruby version and/or gemset can be served separately through Passenger Standalone and hook into the main web server via a reverse proxy configuration (step 6).<br />
<br />
=== Step 5: .rvmrc files and ownerships ===<br />
<br />
This step is crucial for the correct behaviour of the setup. RVM seeks for .rvmrc files when changing folders; if it finds one, it reads it. In these files normally one stores a line like<br />
rvm <ruby_version>@<gemset_name><br />
so the specified environment is set at the entrance of applications' root folder.<br />
<br />
Create /srv/http/refineria/.rvmrc doing<br />
sudo sh -c 'echo "rvm ree@refinery" > /srv/http/refineria/.rvmrc'<br />
, and /srv/http/navegador/.rvmrc with<br />
sudo sh -c 'echo "rvm 1.9.3@browser" > /srv/http/navegador/.rvmrc'<br />
You have to enter to both application root folders now, because every first time that RVM finds a .rvmrc it asks you if you trust the given file, consequently you must validate the two files you have just created.<br />
<br />
These files aid the programs involved to find the correct gems.<br />
<br />
Apart, if applications' files and folders are not owned by the right user you will face database write-access problems. The use of rvmsudo produces ''root''-owned archives when generated by Rails; in the other hand, ''nobody'' is the user for Passenger —if you have not changed it—: who will use and should posses them. Fix this doing<br />
$ sudo chown -R nobody.nobody /srv/http/refineria /srv/http/navegador<br />
<br />
=== Step 6: Reverse proxies ===<br />
<br />
You have to start the Passenger Standalone web servers for your applications. So, do<br />
$ cd /srv/http/refineria<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
and<br />
$ cd /srv/http/navegador<br />
$ rvmsudo passenger start --socket tmp/sockets/passenger.socket -d<br />
. The first time that you run a Passenger Standalone it will perform a minor installation.<br />
<br />
Note that you are using ''unix domain'' sockets instead of the commonly-used ''TCP'' sockets; it turns out that unix domain are significantly faster than TCP sockets.<br />
<br />
{{note|If you are experimenting trouble with unix sockets, changing to TCP should work:<br />
rvmsudo passenger start -a 127.0.0.1 -p 3000 -d<br />
}}<br />
<br />
==== Launch Passenger Standalone daemons at system start-up ====<br />
<br />
''Do you have a script? Please post it here.''<br />
<br />
=== Step 7: Deployment ===<br />
<br />
Once again edit /opt/nginx/conf/nginx.conf to include some vital instructions:<br />
<br />
<pre><br />
## RefineryCMS ##<br />
<br />
server {<br />
server_name refinery.domain.com;<br />
root /srv/http/refineria/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/refineria/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
<br />
## BrowserCMS ##<br />
<br />
server {<br />
server_name browser.domain.com;<br />
root /srv/http/navegador/public;<br />
location / {<br />
proxy_pass http://unix:/srv/http/navegador/tmp/sockets/passenger.socket;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
{{note|Or if using TCP sockets, configure the ''proxy_pass'' directive like<br />
<pre>proxy_pass http://127.0.0.1:3000;</pre><br />
}}<br />
<br />
At this point you are in conditions to run Nginx with:<br />
<br />
$ sudo rc.d start nginx<br />
<br />
and to access both CMSs through ''refinery.domain.com'' and ''browser.domain.com''.<br />
<br />
=== References ===<br />
<br />
* http://beginrescueend.com/integration/passenger<br />
* http://blog.phusion.nl/2010/09/21/phusion-passenger-running-multiple-ruby-versions<br />
<br />
== See also ==<br />
<br />
* [[Ruby]]<br />
* [[Nginx]]<br />
* [[LAMP]]<br />
* [[MySQL]]<br />
<br />
== References ==<br />
<br />
* Ruby on Rails http://rubyonrails.org/download.<br />
* Mongrel http://mongrel.rubyforge.org.</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Initscripts/rc.conf&diff=216884Initscripts/rc.conf2012-08-07T17:54:53Z<p>Lfxgroove: /* Modules */ Added a link to load devices</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Boot process]]<br />
[[cs:Rc.conf]]<br />
[[de:rc.conf]]<br />
[[es:Rc.conf]]<br />
[[fr:rc.conf]]<br />
[[it:Rc.conf]]<br />
[[nl:Rc.conf]]<br />
[[ro:rc.conf]]<br />
[[ru:Rc.conf]]<br />
[[sr:Rc.conf]]<br />
[[tr:rc.conf]]<br />
[[uk:Rc.conf]]<br />
[[zh-CN:Rc.conf]]<br />
{{Lowercase title}}<br />
{{Article summary start}}<br />
{{Article summary text|Details the core system configuration file used in Arch Linux.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Arch Boot Process}}<br />
{{Article summary end}}<br />
<br />
{{Out of date|The overall look of the {{ic|rc.conf}} file has recently (July 2012) changed. Many of the comments have been moved and expanded into a manpage, and options unrelated to initscripts were deprecated and removed from the default file.}}<br />
<br />
{{ic|/etc/rc.conf}} is the configuration file for Arch's initscripts. It configures what daemons to start at boot, the basic network daemon, and certain aspects of hardware discovery.<br />
<br />
==Overview==<br />
<br />
This is what a typical {{ic|rc.conf}} file looks like on an up-to-date Arch install. ([https://projects.archlinux.org/initscripts.git/tree/rc.conf current version]):<br />
<br />
{{hc|/etc/rc.conf|<nowiki><br />
#<br />
# /etc/rc.conf - configuration file for initscripts<br />
#<br />
# Most of rc.conf has been replaced by various other configuration<br />
# files. See archlinux(7) for details.<br />
#<br />
# For more details on rc.conf see rc.conf(5).<br />
#<br />
<br />
DAEMONS=(syslog-ng network crond)<br />
<br />
# Storage<br />
#<br />
# USEDMRAID="no"<br />
# USELVM="no"<br />
<br />
# Network<br />
#<br />
# interface=<br />
# address=<br />
# netmask=<br />
# gateway=<br />
</nowiki>}}<br />
<br />
==Daemons==<br />
; [[DAEMONS]]: A space-separated list of scripts located in {{ic|/etc/rc.d/}} which are started during the boot process. Usually you do not need to change the defaults to get a running system, but you are going to edit this array whenever you install system services like {{ic|sshd}}, and want to start these automatically during boot-up. This is basically Arch's way of handling what others handle with various symlinks to an {{ic|init.d}} directory. For more info see: [[Writing rc.d scripts]]<br />
:# If a script name is prefixed with a bang ({{ic|!}}), it is not executed. <br />
:# If a script is prefixed with an "at" symbol ({{ic|@}}), then it will be executed in the background, i.e. the startup sequence will not wait for successful completion before continuing.<br />
: Example:<br />
: {{bc|<nowiki>DAEMONS=(@syslog-ng !network net-profiles crond sshd)</nowiki>}}<br />
: {{Note|The order in which the daemons are listed is important as they are loaded in that order.}}<br />
<br />
==Hardware==<br />
; USEDMRAID: Scan for FakeRAID (dmraid) Volumes at startup (runs {{ic|dmraid -i -ay}}). <br />
; USELVM: Scan for [[LVM]] volume groups at start-up, which is required if you use LVM. Setting to {{ic|YES}} runs {{ic|vgchange --sysinit -a y}} (handled by activate_vgs() function) during sysinit.<br />
; {{Note|USEBTRFS is no longer needed, as it is taken care of by udev.}}<br />
<br />
=== Interface configuration ===<br />
{{ic|rc.conf}} only supports the configuration of a single interface. For the configuration of multiple interfaces or other advanced network configurations like bridging, use [[netcfg]].<br />
<br />
; interface: name of device (required)<br />
; address: IP address (leave blank for DHCP)<br />
; netmask: subnet mask (ignored for DHCP) (optional, defaults to 255.255.255.0)<br />
; broadcast: broadcast address (ignored for DHCP) (optional)<br />
; gateway: default route (ignored for DHCP)<br />
<br />
{{hc|Static IP Example|<nowiki>interface=eth0<br />
address=192.168.0.2<br />
netmask=255.255.255.0<br />
broadcast=192.168.0.255<br />
gateway=192.168.0.1</nowiki>}}<br />
{{hc|DHCP example|<nowiki>interface=eth0<br />
address=<br />
netmask=<br />
gateway=</nowiki>}}<br />
{{Note|Make sure to add {{ic|network}} to {{ic|DAEMONS}} {{bc|<nowiki>DAEMONS=(... network sshd)</nowiki>}}<br />
or, if using [[netcfg]], add {{ic|net-profiles}} {{bc|<nowiki>DAEMONS=(... !network net-profiles sshd)</nowiki>}}<br />
}}<br />
<br />
==Modules==<br />
; MODULES: {{Warning|Modules to be autoloaded at boot are now specified in {{ic|/etc/modules-load.d/}}, and modules to be blacklisted are now specified in {{ic|/etc/modprobe.d/}}.}}<br />
Modules to load at boot-up in addition to auto-loaded ones, to do this see [[Kernel modules#Loading]], and to blacklist modules, see [[Kernel modules#Blacklisting]].<br />
: {{Note|{{ic|MOD_AUTOLOAD}} is deprecated as of {{Pkg|initscripts}} 2011.06.1-1, you can use [[udev]] rules to achieve the same effect.}}<br />
: {{Tip|Some modules may not be loaded in the order they are listed, as they might also be loaded on-demand by [[udev]]. For consistent network interface names between boots, create the [[Udev#Mixed_Up_Devices.2C_Sound.2FNetwork_Cards_Changing_Order_Each_Boot|appropriate udev rules]].}}<br />
<br />
==Localization==<br />
; HARDWARECLOCK: {{Warning|This setting is now configured in {{ic|/etc/adjtime}}.}} Specifies whether the hardware clock, which is synchronized from on bootup and to on shutdown, stores {{ic|UTC}} time, or the {{ic|localtime}}. If this value is not set, then the value stored by hwclock in {{ic|/var/lib/hwclock/adjtime}} is used instead. See [[Time]] for more information.<br />
:# {{ic|UTC}} makes sense because it greatly simplifies changing timezones and daylight savings time. Linux will change to-and-from DST, regardless of whether Linux was running at the time DST is entered or left.<br />
:# {{ic|localtime}} is necessary if you dual boot with an operating system that only stores {{ic|localtime}}, such as Windows. Linux will not adjust the time, operating under the assumption that your system may be a dual-boot system at that time and that the other OS takes care of the DST switch. If that was not the case, the DST change needs to be made manually.<br />
:# empty: fall back to the value in {{ic|/var/lib/hwclock/adjtime}}, which defaults to UTC. This is recommended as other users of hwclock might change the adjtime file and hence cause rc.conf and adjtime to be out of sync<br />
:# any other value will result in the hardware clock being left untouched (useful for virtualization)<br />
; [[TIMEZONE]]: {{Warning|This setting is now configured by the {{ic|/etc/localtime}} symlink.}} Specifies your time zone. Possible time zones are the relative path to a zoneinfo file starting from the directory {{ic|/usr/share/zoneinfo}}. For example, a German timezone would be {{ic|Europe/Berlin}}, which refers to the file {{ic|/usr/share/zoneinfo/Europe/Berlin}}.<br />
; [[KEYMAP]]: {{Warning|This setting is now configured in {{ic|/etc/vconsole.conf}}.}} The keyboard layout you want to use. If you live in the US, you probably use qwerty, which is referred using us (default). The available keymaps are in {{ic|/usr/share/kbd/keymaps}}. {{Note|Please note that this setting is only valid for your TTYs, not any graphical window managers or X!}}<br />
<br />
; [[Fonts#Console_fonts|CONSOLEFONT]]: {{Warning|This setting is now configured in {{ic|/etc/vconsole.conf}}.}} Defines the console font to load with the {{ic|setfont}} program on boot-up (ter-v14b for example). Possible fonts are found in {{ic|/usr/share/kbd/consolefonts}} (only needed for non-US). {{ic|FONT}} in {{ic|/etc/vconsole.conf}} takes precedence. For more info see: [[Fonts#Console_fonts|Console fonts]]<br />
; [[Fonts#Console_fonts|CONSOLEMAP]]: {{Warning|This setting is now configured in {{ic|/etc/vconsole.conf}}.}} Defines the console map to load with the {{ic|setfont}} program on boot-up (8859-1_to_uni for example). Possible maps are found in {{ic|/usr/share/kbd/consoletrans}}. You will want to set this to a map suitable for your locale (8859-1 for Latin1, for example) if you use an utf8 locale above and use programs that generate 8-bit output. {{ic|FONT_MAP}} in {{ic|/etc/vconsole.conf}} takes precedence. {{Note|If using X11 for everyday work, note that this only affects the output of console applications.}}<br />
; [[LOCALE]]: {{Warning|This setting is now configured in {{ic|/etc/locale.gen}}. Run {{ic|locale-gen}} to update changes. The system-wide locale can be set in {{ic|/etc/locale.conf}}.}} This sets your system language, which will be used by all i18n-friendly applications and utilities. You can get a list of the available locales by running {{ic|locale -a}} from the command line. This setting's default is fine for US English users. The {{ic|LANG}} variable in {{ic|[[locale.conf|/etc/locale.conf]]}} takes precedence if it is set, and users of login shells that cannot source {{ic|/etc/rc.conf}}, should set that value instead.<br />
; DAEMON_LOCALE: {{Warning|This setting is obsolete.}} If set to yes, use {{ic|$LOCALE}} as the locale during daemon startup and during the boot process. If set to no, the '''C''' locale is used. Default value is yes.<br />
; USECOLOR: {{Warning|This setting is obsolete.}} Enable (or disable) colorized status messages during boot-up.<br />
<br />
==Networking==<br />
; [[HOSTNAME]]: {{Warning|Unless {{ic|nss-$HOSTNAME}} is used, this setting is now configured in {{ic|/etc/hostname}}. Remember to modify {{ic|/etc/hosts}} to match.}} Set this to the hostname of the machine, without the domain part. This is totally your choice, as long as you stick to letters, digits and a few common special characters like the dash. Should also be put in {{ic|/etc/hosts}}. The contents of {{ic|/etc/hostname}} (if not empty) takes precedence.<br />
<br />
=== Network Persist ===<br />
The {{ic|NETWORK_PERSIST}} variable tells the system whether or not to skip network shutdown. This is required if your root device is on NFS. The default setting is "no".<br />
# default<br />
NETWORK_PERSIST="no"<br />
<br />
# NFS-based root device<br />
# NETWORK_PERSIST="yes"</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=User_talk:Lfxgroove&diff=215712User talk:Lfxgroove2012-07-31T05:09:25Z<p>Lfxgroove: </p>
<hr />
<div>https://wiki.archlinux.org/index.php?title=GRUB2&diff=214412&oldid=214411<br />
is not a *minor* edit. <br />
<br />
"Minor" pertains to grammar, punctuation, spelling, and the like.<br />
Just a friendly reminder.<br />
https://wiki.archlinux.org/index.php/Help:Editing#Editing<br />
<br />
Okay, just quickly added it and didn't read the editing guidelines, sorry!</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=GRUB&diff=214412GRUB2012-07-24T06:49:04Z<p>Lfxgroove: /* Boot Microsoft Windows installed in BIOS-MBR mode */</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[cs:GRUB2]]<br />
[[es:GRUB2]]<br />
[[fr:GRUB2]]<br />
[[id:GRUB2]]<br />
[[it:GRUB2]]<br />
[[ru:GRUB2]]<br />
[[tr:GRUB2]]<br />
[[zh-CN:GRUB2]]<br />
[[zh-TW:GRUB2]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers various aspects of the next generation of the GRand Unified Bootloader (GRUB2).}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Burg}} - Burg is a brand-new boot loader based on GRUB2. It uses a new object format which allows it to be built in a wider range of OS, including Linux, Windows, OS X, Solaris, FreeBSD, etc. It also has a highly configurable menu system which works in both text and graphic mode. <br />
{{Article summary heading|Resources}}<br />
{{Article summary link|GNU GRUB -- GNU Project|https://www.gnu.org/software/grub/}}<br />
{{Article summary end}}<br />
<br />
[https://www.gnu.org/software/grub/ GRUB2] is the next generation of the GRand Unified Bootloader (GRUB). GRUB2 is derived from [http://www.nongnu.org/pupa/ PUPA] which was a research project to investigate the next generation of GRUB. GRUB2 has been rewritten from scratch to clean up everything and provide modularity and portability [https://www.gnu.org/software/grub/grub-faq.en.html#q1].<br />
<br />
In brief, the ''bootloader'' is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the Linux kernel. The kernel, in turn, initializes the rest of the operating system.<br />
<br />
== Preface ==<br />
Here is some information needs to be clarified:<br />
* The name ''GRUB'' officially refers to version ''2'' of the software, see [https://www.gnu.org/software/grub/]. If you are looking for the article on the legacy version, see [[GRUB Legacy]].<br />
<br />
* [[GRUB Legacy]] (i.e. version 0.9x) is considered legacy by upstream and is being replaced by GRUB2 and [[Syslinux]] in Arch Linux. See the news [https://www.archlinux.org/news/grub-legacy-no-longer-supported/ here]. Upstream recommends GRUB2 >=1.99 over GRUB Legacy, even for current GRUB Legacy users.<br />
<br />
* The [[Archboot]] ISO's installer script supports {{Pkg|grub-bios}} and {{Pkg|grub-efi-x86_64}} installation. The official installer script AIF (Arch Installation Framework) does not support GRUB(2) yet.<br />
<br />
* From 1.99-6 onwards, GRUB2 supports [[Btrfs]] as root (without a separate {{ic|/boot}} filesystem) compressed with either zlib or LZO.<br />
<br />
* For GRUB2 UEFI info, it is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this page.<br />
<br />
=== Notes for current GRUB Legacy users ===<br />
* Although GRUB legacy will not be removed from your system and will stay fully functional, you should consider upgrading to GRUB version 2.x, or one of the other supported bootloaders.<br />
<br />
* Upgrade from [[GRUB Legacy]] to [[GRUB]](2) is the much same as installing GRUB from a running Arch Linux which is covered [[#From a running Arch Linux|below]].<br />
<br />
* There are differences in the commands of GRUB and GRUB2. Familiarize yourself with [https://www.gnu.org/software/grub/manual/grub.html#Commands GRUB2 commands] before proceeding (e.g. "find" has been replaced with "search").<br />
<br />
* GRUB2 is now ''modular'' and no longer requires "stage 1.5". As a result, the bootloader itself is limited -- modules are loaded from the hard drive as needed to expand functionality (e.g. for [[LVM]] or RAID support).<br />
<br />
* Device naming has changed between GRUB and GRUB2. Partitions are numbered from 1 instead of 0 while drives are still numbered from 0, and prefixed with partition-table type. For example, {{ic|/dev/sda1}} would be referred to as {{ic|(hd0,msdos1)}} (for MBR) or {{ic|(hd0,gpt1)}} (for GPT) using GRUB2.<br />
<br />
=== Preliminary Requirements for GRUB2 ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== [[GPT]] specific instructions =====<br />
<br />
GRUB2 in BIOS-GPT configuration requires a BIOS Boot Partition to embed its {{ic|core.img}} in the absence of post-MBR gap in GPT partitioned systems (which is taken over by the GPT Primary Header and Primary Partition table). This partition is used by GRUB2 only in BIOS-GPT setups. No such partition type exists in case of MBR partitioning (at least not for GRUB2). This partition is also not required if the system is UEFI based, as no embedding of bootsectors takes place in that case. Syslinux does not require this partition.<br />
<br />
For a BIOS-GPT configuration, create a 2 MiB partition using cgdisk or GNU Parted with no filesystem. The location of the partition in the partition table does not matter but it should be within the first 2 TiB region of the disk. It is advisable to put it somewhere in the beginning of the disk before the {{ic|/boot}} partition. Set the partition type to "EF02" in cgdisk or {{ic|set <BOOT_PART_NUM> bios_grub on}} in GNU Parted.<br />
<br />
{{Note|This partition should be created before {{ic|grub-install}} or {{ic|grub-setup}} is run or before the '''Install Bootloader''' step of the Archlinux installer (if GRUB2 BIOS is selected as bootloader).}}<br />
<br />
===== [[MBR]] aka msdos partitioning specific instructions =====<br />
<br />
Usually the post-MBR gap (after the 512 byte MBR region and before the start of the 1st partition) in many MBR (or msdos disklabel) partitioned systems is 32 KiB when DOS compatibility cylinder alignment issues are satisfied in the partition table. However a post-MBR gap of about 1 to 2 MiB is recommended to provide sufficient room for embedding GRUB2's {{ic|core.img}} ({{bug|24103}}). It is advisable to use a partitioner which supports 1 MiB partition alignment to obtain this space as well as satisfy other non-512 byte sector issues (which are unrelated to embedding of {{ic|core.img}}).<br />
<br />
If you do not dual-boot with MS Windows (any version) in BIOS systems, it is advisable to switch to GPT partitioning - [[GUID_Partition_Table#Convert_from_MBR_to_GPT]]<br />
<br />
{{Note|Create the 2MiB partition mentioned above BEFORE you convert to GPT. If you do not, gparted will not resize your boot partition to allow its creation, and when you reboot GRUB2 will not know where to look.}}<br />
<br />
==== UEFI systems ====<br />
<br />
===== Create and Mount the UEFI SYSTEM PARTITION =====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
Follow [[Unified_Extensible_Firmware_Interface#Create_an_UEFI_System_Partition_in_Linux]] for instructions on creating a UEFI SYSTEM PARTITION. Then mount the UEFI SYSTEM PARTITION at {{ic|/boot/efi}}. If you have mounted the UEFISYS partition in some other mountpoint, replace {{ic|/boot/efi}} in the below instructions with that mountpoint:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat <UEFISYS_PART_DEVICE> /boot/efi<br />
<br />
Create a <UEFI_SYSTEM_PARTITION>{{ic|/EFI}} directory, if it does not exist:<br />
<br />
# mkdir -p /boot/efi/EFI<br />
<br />
== Installation ==<br />
<br />
=== During Arch Linux installation ===<br />
<br />
* Skip the '''Install Bootloader''' step and exit the installer.<br />
* Configure the network:<br />
# aif -p partial-configure-network<br />
This will bring up a prompt; put in the network interface to use, (e.g., {{ic|eth0}}) and use DHCP for easy configuration.<br />
* If you did not configure the installed system's {{ic|/etc/resolv.conf}} file during installation (for instance, if you plan to let DHCP generate it later), you will need to copy the one generated by AIF when it configured the network:<br />
# cp /etc/resolv.conf /mnt/etc/resolv.conf<br />
* If you run into network issues in the pacman update step below, you may have needed to install the {{Pkg|net-tools}} package.<br />
* Check and see if the {{ic|dm_mod}} module is loaded. If it is not, load it manually:<br />
# lsmod | grep dm_mod<br />
# modprobe dm-mod<br />
{{Note|This is necessary at this point, and cannot be postponed after the chroot. If you try to use modprobe in a chroot environment that has a later kernel version from that of the installing device (at the time of writing, 2.6.33), modprobe will fail. This happens routinely using the Arch "net" installations.}}<br />
* From the installer's live shell, chroot to the installed system:<br />
# mount -o bind /dev /mnt/dev<br />
# mount -t proc /proc /mnt/proc/<br />
# mount -t sysfs /sys /mnt/sys/<br />
# chroot /mnt bash<br />
* Refresh the package list (with an extra {{ic|-y}} flag to force a refresh of all package lists even if they appear to be up to date):<br />
# pacman -Syy<br />
* Install the GRUB2 package as mentioned in the section [[#From a running Arch Linux]] (Note that the {{ic|dm-mod}} module has already been loaded, no need to do that again).<br />
<br />
=== From a running Arch Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Backup Important Data =====<br />
<br />
Although a GRUB(2) installation should run smoothly, it is strongly recommended to keep the GRUB Legacy files before installing {{Pkg|grub-bios}}.<br />
<br />
# mv /boot/grub /boot/grub-legacy<br />
<br />
Backup the MBR which contains the boot code and partition table (Replace {{ic|/dev/sd'''X'''}} with your actual disk path)<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/mbr_backup bs=512 count=1<br />
<br />
Only 446 bytes of the MBR contain boot code, the next 64 contain the partition table. If you do not want to overwrite your partition table when restoring, it is strongly advised to backup only the MBR boot code:<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/bootcode_backup bs=446 count=1<br />
<br />
If unable to install GRUB2 correctly, see [[GRUB2#Restore_GRUB_Legacy]].<br />
<br />
===== Install grub-bios package =====<br />
<br />
The GRUB(2) packages can be installed with pacman (and will replace {{Pkg|grub-legacy}} or {{Pkg|grub}}, if it is installed):<br />
<br />
# pacman -S grub-bios<br />
<br />
{{Note|Simply installing the package won't update the {{ic|/boot/grub/i386-pc/core.img}} file and the GRUB(2) modules in {{ic|/boot/grub/i386-pc}}. You need to update them manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm_mod<br />
<br />
===== Install grub-bios boot files =====<br />
<br />
There are 3 ways to install GRUB(2) boot files in BIOS booting:<br />
*[[#Install_to_440-byte_MBR_boot_code_region]] (recommended) , <br />
*[[#Install_to_Partition_or_Partitionless_Disk]] (not recommended),<br />
*[[#Generate_core.img_alone]] (safest method, but requires another BIOS bootloader like [[grub-legacy]] or [[syslinux]] to be installed to chainload {{ic|/boot/grub/i386-pc/core.img}}). <br />
<br />
====== Install to 440-byte MBR boot code region ======<br />
<br />
To setup {{ic|grub-bios}} in the 440-byte Master Boot Record boot code region, populate the {{ic|/boot/grub}} directory, generate the {{ic|/boot/grub/i386-pc/core.img}} file, and embed it in the 32 KiB (minimum size - varies depending on partition alignment) post-MBR gap (MBR disks) or in BIOS Boot Partition (GPT disks), run:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
where {{ic|/dev/sda}} is the destination of the installation (in this case the MBR of the first SATA disk). If you use [[LVM]] for your {{ic|/boot}}, you can install GRUB2 on multiple physical disks. <br />
<br />
The {{ic|--no-floppy}} tells {{ic|grub-bios}} utilities not to search for any floppy devices which reduces the overall execution time of {{ic|grub-install}} on many systems (it will also prevent the issue below from occurring). Otherwise you get an error that looks like this:<br />
<br />
grub-probe: error: Cannot get the real path of '/dev/fd0'<br />
Auto-detection of a filesystem module failed.<br />
Please specify the module with the option '--modules' explicitly.<br />
<br />
{{Note|{{ic|--no-floppy}} has been removed from {{ic|grub-install}} in 2.00~beta2 upstream release, and replaced with {{ic|--allow-floppy}}.}}<br />
<br />
{{Warning|Make sure to check the {{ic|/boot}} directory if you use the latter. Sometimes the {{ic| boot-directory}} parameter creates another {{ic|/boot}} folder inside of {{ic|/boot}}. A wrong install would look like: {{ic|/boot/boot/grub/}}.}}<br />
<br />
====== Install to Partition or Partitionless Disk ======<br />
<br />
{{Note|{{ic|grub-bios}} (any version - including upstream Bazaar repo) does not encourage installation to a partition boot sector or a partitionless disk like GRUB Legacy or syslinux does. This kind of setup is prone to breakage, especially during updates, and is not supported by Arch devs.}}<br />
<br />
To set up {{ic|grub-bios}} to a partition boot sector, to a partitionless disk (also called superfloppy) or to a floppy disk, run (using for example {{ic|/dev/sdaX}} as the {{ic|/boot}} partition):<br />
<br />
# chattr -i /boot/grub/i386-pc/core.img<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --force --debug /dev/sdaX<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# chattr +i /boot/grub/i386-pc/core.img<br />
<br />
You need to use the {{ic|--force}} option to allow usage of blocklists and should not use {{ic|1=--grub-setup=/bin/true}} (which is similar to simply generating {{ic|core.img}}).<br />
<br />
{{ic|grub-install}} will give out warnings like which should give you the idea of what might go wrong with this approach:<br />
<br />
/sbin/grub-setup: warn: Attempting to install GRUB to a partitionless disk or to a partition. This is a BAD idea.<br />
/sbin/grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. <br />
However, blocklists are UNRELIABLE and their use is discouraged.<br />
<br />
Without {{ic|--force}} you may get the below error and {{ic|grub-setup}} will not setup its boot code in the partition boot sector:<br />
<br />
/sbin/grub-setup: error: will not proceed with blocklists<br />
<br />
With {{ic|--force}} you should get:<br />
<br />
Installation finished. No error reported.<br />
<br />
The reason why {{ic|grub-setup}} does not by default allow this is because in case of partition or a partitionless disk is that {{ic|grub-bios}} relies on embedded blocklists in the partition bootsector to locate the {{ic|/boot/grub/i386-pc/core.img}} file and the prefix dir {{ic|/boot/grub}}. The sector locations of {{ic|core.img}} may change whenever the filesystem in the partition is being altered (files copied, deleted etc.). For more info see https://bugzilla.redhat.com/show_bug.cgi?id=728742 and https://bugzilla.redhat.com/show_bug.cgi?id=730915.<br />
<br />
The workaround for this is to set the immutable flag on {{ic|/boot/grub/i386-pc/core.img}} (using chattr command as mentioned above) so that the sector locations of the {{ic|core.img}} file in the disk is not altered. The immutable flag on {{ic|/boot/grub/i386-pc/core.img}} needs to be set only if {{ic|grub-bios}} is installed to a partition boot sector or a partitionless disk, not in case of installtion to MBR or simple generation of {{ic|core.img}} without embedding any bootsector (mentioned above).<br />
<br />
====== Generate core.img alone ======<br />
<br />
To populate the {{ic|/boot/grub}} directory and generate a {{ic|/boot/grub/i386-pc/core.img}} file '''without''' embedding any {{ic|grub-bios}} bootsector code in the MBR, post-MBR region, or the partition bootsector, add {{ic|1=--grub-setup=/bin/true}} to {{ic|grub-install}}:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --grub-setup=/bin/true --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
You can then chainload GRUB2's {{ic|core.img}} from GRUB Legacy or syslinux as a Linux kernel or a multiboot kernel.<br />
<br />
===== Generate GRUB2 BIOS Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|/boot/grub/grub.cfg}}, NOT {{ic|/boot/grub/i386-pc/grub.cfg}}.}}<br />
<br />
If grub2 complains about "no suitable mode found" while booting, go to [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
If {{ic|grub-mkconfig}} fails, convert your {{ic|/boot/grub/menu.lst}} file to {{ic|/boot/grub/grub.cfg}} using:<br />
<br />
# grub-menulst2cfg /boot/grub/menu.lst /boot/grub/grub.cfg<br />
<br />
For example:<br />
<br />
{{hc|/boot/grub/menu.lst|<nowiki><br />
default=0<br />
timeout=5<br />
<br />
title Arch Linux Stock Kernel<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux.img<br />
<br />
title Arch Linux Stock Kernel Fallback<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux-fallback.img<br />
</nowiki>}}<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set default='0'; if [ x"$default" = xsaved ]; then load_env; set default="$saved_entry"; fi<br />
set timeout=5<br />
<br />
menuentry 'Arch Linux Stock Kernel' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux.img' '/initramfs-linux.img'<br />
<br />
}<br />
<br />
menuentry 'Arch Linux Stock Kernel Fallback' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux-fallback.img' '/initramfs-linux-fallback.img'<br />
}<br />
</nowiki>}}<br />
<br />
If you forgot to create a GRUB2 {{ic|/boot/grub/grub.cfg}} config file and simply rebooted into GRUB2 Command Shell, type:<br />
<br />
sh:grub> insmod legacycfg<br />
sh:grub> legacy_configfile ${prefix}/menu.lst<br />
<br />
Boot into Arch and re-create the proper GRUB2 {{ic|/boot/grub/grub.cfg}} config file.<br />
<br />
{{Note|This option works only in BIOS systems, not in UEFI systems.}}<br />
<br />
===== Multiboot in BIOS =====<br />
<br />
====== Boot Microsoft Windows installed in BIOS-MBR mode ======<br />
<br />
{{Note|GRUB2 supports booting {{ic|bootmgr}} directly and chainload of partition boot sector is no longer required to boot Windows in a BIOS-MBR setup.}}<br />
<br />
{{Warning|Take note that it is the SYSTEM PARTITION that has the bootmgr, not your "real" windows partition, ie: when showing all UUID's with blkid it is the partition with LABEL&#61;"SYSTEM RESERVED" which is only about 100 mb big much like the boot partition for arch. See http://en.wikipedia.org/wiki/System_partition_and_boot_partition for some more info.}}<br />
<br />
Find the UUID of the NTFS filesystem of the Windows's SYSTEM PARTITION where the {{ic|bootmgr}} and its files reside. For example, if Windows {{ic|bootmgr}} exists at {{ic|/media/Windows/bootmgr}}:<br />
<br />
# grub-probe --target=fs_uuid /media/Windows/bootmgr<br />
69B235F6749E84CE<br />
<br />
Then, add the below code to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} and regenerate {{ic|grub.cfg}} with {{ic|grub-mkconfig}} as explained above to boot Windows (Vista, 7 or 8) installed in BIOS-MBR mode:<br />
<br />
<pre><br />
menuentry "Microsoft Windows 7 BIOS-MBR" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}</pre><br />
<br />
For Windows XP:<br />
<br />
menuentry "Microsoft Windows XP" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /ntldr<br />
}<br />
<br />
==== UEFI systems ====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
===== Install grub-uefi package =====<br />
<br />
{{Note|Unless specified as EFI 1.x , EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitely, the instructions are general and not Mac specific. Some of them may not work or may be different in Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one UEFI Specification version and is therefore not a standard UEFI firmware.}}<br />
<br />
GRUB2 UEFI bootloader is available in Arch Linux only from version 1.99~rc1. To install, first [[Unified_Extensible_Firmware_Interface#Detecting_UEFI_Firmware_Arch|detect which UEFI firmware arch]] you have (either x86_64 or i386).<br />
<br />
Depending on that, install the appropriate package<br />
<br />
For 64-bit aka x86_64 UEFI firmware:<br />
# pacman -S grub-efi-x86_64<br />
<br />
For 32-bit aka i386 UEFI firmware:<br />
# pacman -S grub-efi-i386<br />
<br />
{{Note|Simply installing the package will not update the {{ic|grub.efi}} file and the GRUB(2) modules in the UEFI System Partition. You need to do this manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm-mod<br />
<br />
===== Install grub-uefi boot files =====<br />
<br />
====== Install to UEFI SYSTEM PARTITION ======<br />
<br />
{{Note|The below commands assume you are using {{ic|grub-efi-x86_64}} (for {{ic|grub-efi-i386}} replace {{ic|x86_64}} with {{ic|i386}} in the below commands).}}<br />
<br />
The UEFI system partition will need to be mounted at {{ic|/boot/efi/}} for the GRUB2 install script to detect it:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat /dev/sdXY /boot/efi<br />
<br />
Install GRUB UEFI application to {{ic|/boot/efi/EFI/arch_grub}} and its modules to {{ic|/boot/grub/x86_64-efi}} (recommended) using:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot --recheck --debug<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
If you want to install grub2 modules and {{ic|grub.cfg}} at the directory {{ic|/boot/efi/EFI/grub}} and the {{ic|grubx64.efi}} application at {{ic|/boot/efi/EFI/arch_grub}} use:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot/efi/EFI --recheck --debug<br />
# mkdir -p /boot/efi/EFI/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/efi/EFI/grub/locale/en.mo<br />
<br />
In this case {{ic|grub-efi-x86_64}} will be installed into {{ic|/boot/grub}}, making the behavior consistent with the BIOS verion of GRUB2, but this is not recommended if you use both {{ic|grub-bios}} and {{ic|grub-efi-x86_64}} in your system, as this will overwrite {{ic|grub-bios }}modules in {{ic|/boot/grub}}.<br />
<br />
The {{ic|--efi-directory}} option mentions the mountpoint of UEFI SYSTEM PARTITION , {{ic|--bootloader-id}} mentions the name of the directory used to store the {{ic|grubx64.efi}} file and {{ic|--boot-directory}} mentions the directory wherein the actual modules will be installed (and into which {{ic|grub.cfg}} should be created).<br />
<br />
The actual paths are:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi<br />
<br />
<boot-directory>/grub/x86_64-efi/<all modules, grub.efi, core.efi, grub.cfg><br />
<br />
{{Note|the {{ic|--bootloader-id}} option does not change {{ic|<boot-directory>/grub}}, i.e. you cannot install the modules to {{ic|<boot-directory>/<bootloader-id>}}, the path is hard-coded to be {{ic|<boot-directory>/grub}}.}}<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == <boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
The {{ic|<nowiki><efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi</nowiki>}} is an exact copy of {{ic|<nowiki><boot-directory>/grub/x86_64-efi/core.efi</nowiki>}}.<br />
<br />
{{Note|In GRUB2 2.00~beta4, the {{ic|grub-install}} option {{ic|--efi-directory}} replaces {{ic|--root-directory}} and the latter is deprecated.}}<br />
{{Note|The options {{ic|--efi-directory}} and {{ic|--bootloader-id}} are specific to GRUB2 UEFI.}}<br />
<br />
In all the cases the UEFI SYSTEM PARTITION should be mounted for {{ic|grub-install}} to install {{ic|grubx64.efi}} in it, which will be launched by the firmware (using the {{ic|efibootmgr}} created boot entry in non-Mac systems).<br />
<br />
If you notice carefully, there is no <device_path> option (Eg: {{ic|/dev/sda}}) at the end of the {{ic|grub-install}} command unlike the case of setting up GRUB2 for BIOS systems. Any <device_path> provided will be ignored by the install script as UEFI bootloaders do not use MBR or Partition boot sectors at all.<br />
<br />
You may now be able to UEFI boot your system by creating a {{ic|grub.cfg}} file by following [[#Generate_GRUB2_UEFI_Config_file]] and [[#Create_GRUB2_entry_in_the_Firmware_Boot_Manager]].<br />
<br />
===== Create GRUB2 entry in the Firmware Boot Manager =====<br />
<br />
====== Non-Mac UEFI systems ======<br />
<br />
{{ic|grub-install}} will ensure that {{ic|/boot/efi/EFI/arch_grub/grubx64.efi}} is launched by default if it detects {{ic|efibootmgr}} and if it is able to access UEFI Runtime Services. Follow [[Unified_Extensible_Firmware_Interface#efibootmgr]] for more info.<br />
<br />
If you have problems running GRUB2 in UEFI mode you can try the following (worked on an ASUS Z68 mainboard):<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/tools/shellx64.efi<br />
<br />
After this launch the UEFI Shell from the UEFI setup/menu (in ASUS UEFI BIOS, switch to advanced mode, press Exit in the top right corner and choose "Launch EFI shell from filesystem device"). The GRUB2 menu will show up and you can boot into your system. Afterwards you can use efibootmgr to setup a menu entry (see above).<br />
<br />
====== Apple Mac EFI systems ======<br />
<br />
{{Note|TODO: GRUB upstream Bazaar mactel branch http://bzr.savannah.gnu.org/lh/grub/branches/mactel/changes. No further update from grub developers.}}<br />
{{Note|TODO: Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}. Requires more testing.}}<br />
<br />
Use bless command from within Mac OS X to set {{ic|grubx64.efi}} as the default boot option. You can also boot from the Mac OS X install disc and launch a Terminal there if you only have Linux installed. In the Terminal, create a directory and mount the EFI System Partition:<br />
<br />
# cd /Volumes<br />
# mkdir efi<br />
# mount -t msdos /dev/disk0s1 /Volumes/efi<br />
<br />
Then run bless on {{ic|grub.efi}} and on the EFI partition to set them as the default boot options.<br />
<br />
# bless --folder=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
# bless --mount=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
<br />
More info at https://help.ubuntu.com/community/UEFIBooting#Apple_Mac_EFI_systems_.28both_EFI_architecture.29.<br />
<br />
===== Generate GRUB2 UEFI Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o <boot-directory>/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|<boot-directory>/grub/grub.cfg}}, NOT {{ic|<boot-directory>/grub/x86_64-efi/grub.cfg}}.}}<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot/efi/EFI</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/efi/EFI/grub/grub.cfg<br />
<br />
This is independent of the value of {{ic|--bootloader-id}} option.<br />
<br />
If GRUB2 complains about "no suitable mode found" while booting, try [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
===== Create GRUB2 Standalone UEFI Application =====<br />
<br />
It is possible to create a {{ic|grubx64_standalone.efi}} application which has all the modules embeddded in a memdisk within the uefi application, thus removing the need for having a separate directory populated with all the GRUB2 uefi modules and other related files. This is done using the {{ic|grub-mkstandalone}} command which is included in {{Pkg|grub-common}} >= 1:1.99-6 package.<br />
<br />
The easiest way to do this would be with the install command already mentioned before, but specifying the modules to include. For example:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" <any extra files you want to include><br />
<br />
The {{ic|grubx64_standalone.efi}} file expects {{ic|grub.cfg}} to be within its $prefix which is {{ic|(memdisk)/boot/grub}}. The memdisk is embedded within the efi app. The {{ic|grub-mkstandlone}} script allow passing files to be included in the memdisk image to be as the arguments to the script (in <any extra files you want to include>).<br />
<br />
If you have the {{ic|grub.cfg}} at {{ic|/home/user/Desktop/grub.cfg}}, then create a temporary {{ic|/home/user/Desktop/boot/grub/}} directory, copy the {{ic|/home/user/Desktop/grub.cfg}} to {{ic|/home/user/Desktop/boot/grub/grub.cfg}}, cd into {{ic|/home/user/Desktop/boot/grub/}} and run:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" "boot/grub/grub.cfg"<br />
<br />
The reason to cd into {{ic|/home/user/Desktop/boot/grub/}} and to pass the file path as {{ic|boot/grub/grub.cfg}} (notice the lack of a leading slash - boot/ vs /boot/ ) is because {{ic|dir1/dir2/file}} is included as {{ic|(memdisk)/dir1/dir2/file}} by the {{ic|grub-mkstandalone}} script. <br />
<br />
If you pass {{ic|/home/user/Desktop/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/grub.cfg}}. If you pass {{ic|/home/user/Desktop/boot/grub/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/boot/grub/grub.cfg}}. That is the reason for cd'ing into {{ic|/home/user/Desktop/boot/grub/}} and passing {{ic|boot/grub/grub.cfg}}, to include the file as {{ic|(memdisk)/boot/grub/grub.cfg}}, which is what {{ic|grub.efi}} expects the file to be.<br />
<br />
You need to create an UEFI Boot Manager entry for {{ic|/boot/efi/EFI/arch_grub/grubx64_standalone.efi}} using {{ic|efibootmgr}}. Follow [[#Create GRUB2 entry in the Firmware Boot Manager]].<br />
<br />
===== Multiboot in UEFI =====<br />
<br />
====== Chainload Microsoft Windows x86_64 UEFI-GPT ======<br />
<br />
Find the UUID of the FAT32 filesystem in the UEFI SYSTEM PARTITION where the Windows UEFI Bootloader files reside. For example, if Windows {{ic|bootmgfw.efi}} exists at {{ic|/boot/efi/EFI/Microsoft/Boot/bootmgfw.efi}} (ignore the upper-lower case differences since that is immaterial in FAT filesystem):<br />
<br />
# grub-probe --target=fs_uuid /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
1ce5-7f28<br />
<br />
# grub-probe --target=hints_string /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1<br />
<br />
Then, add this code to {{ic|/boot/grub/grub.cfg}} OR {{ic|/boot/efi/EFI/grub/grub.cfg}} to chainload Windows x86_64 (Vista SP1+, 7 or 8) installed in UEFI-GPT mode:<br />
<br />
menuentry "Microsoft Windows x86_64 UEFI-GPT" {<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1 1ce5-7f28<br />
chainloader /efi/Microsoft/Boot/bootmgfw.efi<br />
}<br />
<br />
== Configuration ==<br />
<br />
You can also choose to automatically generate or manually edit {{ic|grub.cfg}}.<br />
<br />
{{Note|For EFI systems, if GRUB2 was installed with the {{ic|--boot-directory}} option set, the {{ic|grub.cfg}} file must be placed in the same directory as {{ic|grubx64.efi}}. Otherwise, the {{ic|grub.cfg}} file goes in {{ic|/boot/grub/}}, just like in the BIOS version of GRUB2.}}<br />
<br />
{{Note|Here is a quite complete description of how to configure GRUB2: http://members.iinet.net/~herman546/p20/GRUB2%20Configuration%20File%20Commands.html }}<br />
<br />
=== Automatically generating using grub-mkconfig (Recommended) ===<br />
<br />
The GRUB2 {{ic|menu.lst}} equivalent configuration files are {{ic|/etc/default/grub}} and {{ic|/etc/grub.d/*}}. {{ic|grub-mkconfig}} uses these files to generate {{ic|grub.cfg}}. By default the script outputs to stdout. To generate a {{ic|grub.cfg}} file run the command:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{ic|/etc/grub.d/10_linux}} is set to automatically add menu items for Arch linux that work out of the box, to any generated configuration. Other operating systems may need to be added manually to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}}<br />
<br />
==== Additional arguments ====<br />
<br />
To pass custom additional arguments to the Linux image, you can set the {{ic|GRUB_CMDLINE_LINUX}} variable in {{ic|/etc/default/grub}}. This is analogous to adding commands to the kernel line in GRUB Legacy.<br />
<br />
For example, use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/sdaX"</nowiki>}} where {{ic|sda'''X'''}} is your swap partition to enable resume after hibernation.<br />
<br />
You can also use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/disk/by-uuid/${swap_uuid}"</nowiki>}}, where {{ic|${swap_uuid} }} is the [[Persistent_block_device_naming|UUID]] of your swap partition.<br />
<br />
Users who have replaced the default SysV init with [[systemd]] will want to add {{ic|<nowiki>init=/bin/systemd</nowiki>}} to their {{ic|<nowiki>GRUB_CMDLINE_LINUX</nowiki>}}.<br />
<br />
=== Manually creating grub.cfg ===<br />
<br />
{{Warning|Editing this file is strongly ''not'' recommended. The file is generated by the {{ic|grub-mkconfig}} command, and it is best to edit your {{ic|/etc/default/grub}} or one of the scripts in the {{ic|/etc/grub.d}} folder.}}<br />
<br />
A basic GRUB config file uses the following options<br />
* {{ic|(hdX,Y)}} is the partition {{ic|Y}} on disk {{ic|X}}, partition numbers starting at 1, disk numbers starting at 0<br />
* {{ic|1=set default=N}} is the default boot entry that is chosen after timeout for user action<br />
* {{ic|1=set timeout=M}} is the time {{ic|M}} to wait in seconds for a user selection before default is booted<br />
* {{ic|<nowiki>menuentry "title" {entry options}</nowiki>}} is a boot entry titled {{ic|title}}<br />
* {{ic|1=set root=(hdX,Y)}} sets the boot partition, where the kernel and GRUB modules are stored (boot need not be a separate partition, and may simply be a directory under the "root" partition ({{ic|/}})<br />
<br />
An example configuration:<br />
<br />
{{hc<br />
|/boot/grub/grub.cfg<br />
|<nowiki><br />
# Config file for GRUB2 - The GNU GRand Unified Bootloader<br />
# /boot/grub/grub.cfg<br />
<br />
# DEVICE NAME CONVERSIONS<br />
#<br />
# Linux Grub<br />
# -------------------------<br />
# /dev/fd0 (fd0)<br />
# /dev/sda (hd0)<br />
# /dev/sdb2 (hd1,2)<br />
# /dev/sda3 (hd0,3)<br />
#<br />
<br />
# Timeout for menu<br />
set timeout=5<br />
<br />
# Set default boot entry as Entry 0<br />
set default=0<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
set root=(hd0,1)<br />
linux /vmlinuz-linux root=/dev/sda3 ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
## (1) Windows<br />
#menuentry "Windows" {<br />
#set root=(hd0,3)<br />
#chainloader +1<br />
#}<br />
</nowiki>}}<br />
<br />
=== Dual-booting ===<br />
<br />
{{Note|If you want GRUB2 to automatically search for other systems, you may wish to install {{Pkg|os-prober}}.}}<br />
<br />
==== Using grub-mkconfig ====<br />
The best way to add other entries is editing the {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} . The entries in this file will be automatically added when running {{ic|grub-mkconfig}}.<br />
After adding the new lines, run:<br />
# grub-mkconfig -o /boot/grub/grub.cfg <br />
to generate an updated {{ic|grub.cfg}}.<br />
<br />
===== With GNU/Linux =====<br />
<br />
Assuming that the other distro is on partition {{ic|sda2}}:<br />
<br />
menuentry "Other Linux" {<br />
set root=(hd0,2)<br />
linux /boot/vmlinuz (add other options here as required)<br />
initrd /boot/initrd.img (if the other kernel uses/needs one)<br />
}<br />
<br />
===== With FreeBSD =====<br />
<br />
Requires that FreeBSD is installed on a single partition with UFS. Assuming it is installed on {{ic|sda4}}:<br />
<br />
menuentry "FreeBSD" {<br />
set root=(hd0,4)<br />
chainloader +1<br />
}<br />
<br />
===== With Windows =====<br />
<br />
This assumes that your Windows partition is {{ic|sda3}}.<br />
<br />
# (2) Windows XP<br />
menuentry "Windows XP" {<br />
set root=(hd0,3)<br />
chainloader (hd0,3)+1<br />
}<br />
<br />
If the Windows bootloader is on an entirely different hard drive than GRUB, it may be necessary to trick Windows into believing that it is the first hard drive. This was possible in GRUB Legacy with {{ic|map}} and is now done with {{ic|drivemap}}. Assuming GRUB is on {{ic|hd0}} and Windows is on {{ic|hd2}}, you need to add the following after {{ic|set root}}:<br />
<br />
drivemap -s hd0 hd2<br />
<br />
==== With Windows via EasyBCD and NeoGRUB ====<br />
<br />
Since EasyBCD's NeoGRUB currently does not understand the GRUB2 menu format, chainload to it by replacing the contents of your {{ic|C:\NST\menu.lst}} file with lines similar to the following:<br />
<br />
default 0<br />
timeout 1<br />
<br />
title Chainload into GRUB v2<br />
root (hd0,7)<br />
kernel /boot/grub/i386-pc/core.img<br />
<br />
===Visual Configuration===<br />
<br />
In GRUB2 it is possible, by default, to change the look of the menu. Make sure to initialize, if not done already, GRUB2 graphical terminal, gfxterm, with proper video mode, gfxmode, in GRUB2. This can be seen in the section [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]]. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload' so any visual configurations need this mode in order to be in effect.<br />
<br />
====Setting the framebuffer resolution ====<br />
<br />
GRUB2 can set the framebuffer for both GRUB2 itself and the kernel. The old {{ic|1=vga=}} way is deprecated. The preferred method is editing {{ic|/etc/default/grub}} as the following sample:<br />
<br />
GRUB_GFXMODE=1024x768x32<br />
GRUB_GFXPAYLOAD_LINUX=keep<br />
<br />
To generate the changes, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
The {{ic|gfxpayload}} property will make sure the kernel keeps the resolution.<br />
<br />
{{Note|If this example does not work for you try to replace {{ic|1=gfxmode="1024x768x32"}} by {{ic|1=vbemode="0x105"}}. Remember to replace the specified resolution with one suitable for your screen.}}<br />
{{Note|To show all the modes you can use {{ic|1=# hwinfo --framebuffer}} (hwinfo is available in [community]), while at GRUB2 prompt you can use the {{ic|1=vbeinfo}} command.}}<br />
<br />
If this method does not work for you, the deprecated {{ic|1=vga=}} method will still work. Just<br />
add it next to the {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="}} line in {{ic|/etc/default/grub}}<br />
for eg: {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vga=792"}} will give you a {{ic|1024x768}} resolution.<br />
<br />
You can choose one of these resolutions: {{ic|640×480}}, {{ic|800×600}}, {{ic|1024×768}}, {{ic|1280×1024}}, {{ic|1600×1200}}<br />
<br />
====915resolution hack ====<br />
<br />
Some times for Intel graphic adapters neither {{ic|1=# hwinfo --framebuffer}} nor {{ic|1=vbeinfo}} will show you the desired resolution. In this case you can use {{ic|915resolution}} hack. This hack will temporarily modify video BIOS and add needed resolution. See [http://915resolution.mango-lang.org/ 915resolution's home page]<br />
<br />
In the following I will proceed with the example for my system. Please adjust the recipe for your needs. First you need to find a video mode which will be modified later. For that, run {{ic|915resolution}} in GRUB2 command shell:<br />
915resolution -l<br />
The output will be something like:<br />
Intel 800/900 Series VBIOS Hack : version 0.5.3<br />
...<br />
Mode 30 : 640x480, 8 bits/pixel<br />
...<br />
Next, our purpose is to overwrite mode 30. (You can choose what ever mode you want.) In the file {{ic|/etc/grub.d/00_header}} just before the {{ic|set gfxmode&#61;${GRUB_GFXMODE}}} line insert:<br />
915resolution 30 1440 900<br />
Here we are overwriting the mode {{ic|30}} with {{ic|1440x900}} resolution. Lastly we need to set {{ic|GRUB_GFXMODE}} as described earlier, regenerate GRUB2 configuration file and reboot to test changes:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# reboot<br />
<br />
====Background image and bitmap fonts====<br />
<br />
GRUB2 comes with support for background images and bitmap fonts in {{ic|pf2}} format. The unifont font is included in the {{Pkg|grub-common}} package under the filename {{ic|unicode.pf2}}, or, as only ASCII characters under the name {{ic|ascii.pf2}}. <br />
<br />
Image formats supported include tga, png and jpeg, providing the correct modules are loaded. The maximum supported resolution depends on your hardware.<br />
<br />
Make sure you have set up the proper [https://wiki.archlinux.org/index.php/GRUB2#Setting_the_framebuffer_resolution framebuffer resolution].<br />
<br />
Edit {{ic|/etc/default/grub}} like this:<br />
GRUB_BACKGROUND="/boot/grub/myimage"<br />
#GRUB_THEME="/path/to/gfxtheme"<br />
<br />
{{Note|If you have installed GRUB on a separate partition, {{ic|/boot/grub/myimage}} becomes {{ic|/grub/myimage}}.}}<br />
<br />
To generate the changes and add the information into {{ic|grub.cfg}}, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If adding the splash image was successful, the user will see {{ic|"Found background image..."}} in the terminal as the command is executed. <br />
If this phrase is not seen, the image information was probably not incorporated into the {{ic|grub.cfg}} file.<br />
<br />
If the image is not displayed, check:<br />
* The path and the filename in {{ic|/etc/default/grub}} are correct.<br />
* The image is of the proper size and format (tga, png, 8-bit jpg).<br />
* The image was saved in the RGB mode, and is not indexed.<br />
* The console mode is not enabled in {{ic|/etc/default/grub}}.<br />
* The command {{ic|grub-mkconfig}} must be executed to place the background image information into the {{ic|/boot/grub/grub.cfg}} file.<br />
<br />
====Theme====<br />
<br />
Here is an example for configuring Starfield theme which was included in GRUB2 package.<br />
<br />
Edit {{ic|/etc/default/grub}}<br />
GRUB_THEME="/boot/grub/themes/starfield/theme.txt"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If configuring the theme was successful, you'll see {{ic|Found theme: /boot/grub/themes/starfield/theme.txt}} in the terminal.<br />
Your splash image will usually not displayed when using a theme.<br />
<br />
====Menu colors====<br />
<br />
As in GRUB Legacy (0.9x), you can change the menu colors in GRUB2. The available colors for GRUB2 are at https://www.gnu.org/software/grub/manual/html_node/Theme-file-format.html#Theme-file-format.<br />
Here is an example:<br />
<br />
Edit {{ic|/etc/default/grub}}:<br />
GRUB_COLOR_NORMAL="light-blue/black"<br />
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Hidden menu====<br />
<br />
One of the unique features of GRUB2 is hiding/skipping the menu and showing it by holding {{keypress|Esc}} when needed. You can also adjust whether you want to see the timeout counter.<br />
<br />
Edit {{ic|/etc/default/grub}} as you wish. Here is an example where the comments from the beginning of the two lines have been removed to enable the feature, the timeout has been set to five seconds and to be shown to the user:<br />
GRUB_HIDDEN_TIMEOUT=5<br />
GRUB_HIDDEN_TIMEOUT_QUIET=false<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Disable framebuffer====<br />
<br />
Users who use NVIDIA proprietary driver might wish to disable GRUB2's framebuffer as it can cause problems with the binary driver.<br />
<br />
To disable framebuffer, edit {{ic|/etc/default/grub}} and uncomment the following line:<br />
GRUB_TERMINAL_OUTPUT=console<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Other Options ===<br />
<br />
==== LVM ====<br />
<br />
If you use [[LVM]] for your {{ic|/boot}}, add the following before menuentry lines:<br />
<br />
insmod lvm<br />
<br />
and specify your root in the menuentry as:<br />
<br />
set root=(''lvm_group_name''-''lvm_logical_boot_partition_name'')<br />
<br />
Example:<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
insmod lvm<br />
set root=(VolumeGroup-lv_boot)<br />
# you can only set following two lines<br />
linux /vmlinuz-linux root=/dev/mapper/VolumeGroup-root ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
==== RAID ====<br />
<br />
GRUB2 provides convenient handling of RAID volumes. You need to add {{ic|insmod raid}} which allows you to address the volume natively. For example, {{ic|/dev/md0}} becomes:<br />
set root=(md0)<br />
<br />
whereas a partitioned RAID volume (e.g. {{ic|/dev/md0p1}}) becomes:<br />
set root=(md0,1)<br />
<br />
==== Persistent block device naming ====<br />
You can use UUIDs to detect partitions instead of the "old" {{ic|/dev/sd*}} and {{ic|/dev/hd*}} scheming. It has the advantage of detecting partitions by their unique UUIDs, which is needed by some people booting with complicated partition setups.<br />
<br />
UUIDs are used by default in the recent versions of GRUB2 - there is no downside in it anyway except that you need to re-generate the {{ic|grub.cfg}} file every time you resize or reformat your partitions. Remember this when modifying partitions with Live-CD.<br />
<br />
The recent versions of GRUB2 use UUIDs by default. You can re-enable the use of UUIDS by simply commenting the UUID line (this is also what it looks like by default):<br />
#GRUB_DISABLE_LINUX_UUID=true<br />
you can also just set the value as {{ic|false}} as shown here:<br />
GRUB_DISABLE_LINUX_UUID=false<br />
<br />
Either way, do not forget to generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Using Labels ====<br />
<br />
It is possible to use labels, human-readable strings attached to filesystems, by using the {{ic|--label}} option to {{ic|search}}. First of all, label your existing partition:<br />
# tune2fs -L a <LABEL> <PARTITION><br />
<br />
Then, add an entry using labels. An example of this:<br />
<br />
menuentry "Arch Linux, session texte" {<br />
search --label --no-floppy --set=root archroot<br />
linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro<br />
initrd /boot/initramfs-linux.img<br />
}<br />
<br />
==== Recall previous entry ====<br />
<br />
GRUB2 can remember the last entry you booted from and use this as the default entry to boot from next time. This is useful if you have multiple kernels (i.e., the current Arch one and the LTS kernel as a fallback option) or operating systems. To do this, edit {{ic|/etc/default/grub}} and change the setting of {{ic|GRUB_DEFAULT}}:<br />
<br />
GRUB_DEFAULT=saved<br />
<br />
This ensures that GRUB will default to the saved entry. To enable saving the selected entry, add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_SAVEDEFAULT=true<br />
<br />
{{Note|Manually added menu items, eg Windows in {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} , will need {{ic|savedefault}} added. Remember to regenerate your configuration file.}}<br />
<br />
==== Security ====<br />
<br />
If you want to secure GRUB2 so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB2's configuration files. To do this, run the command {{ic|grub-mkpasswd_pbkdf2}}. Enter a password and confirm it. The output will look like this:<br />
<br />
{{bc|<nowiki><br />
Your PBKDF2 is grub.pbkdf2.sha512.10000.C8ABD3E93C4DFC83138B0C7A3D719BC650E6234310DA069E6FDB0DD4156313DA3D0D9BFFC2846C21D5A2DDA515114CF6378F8A064C94198D0618E70D23717E82.509BFA8A4217EAD0B33C87432524C0B6B64B34FBAD22D3E6E6874D9B101996C5F98AB1746FE7C7199147ECF4ABD8661C222EEEDB7D14A843261FFF2C07B1269A</nowiki>}}Then, add the following to {{ic|/etc/grub.d/00_header}}:<br />
{{bc|<nowiki>cat << EOF<br />
<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
EOF</nowiki>}}<br />
where {{ic|<password>}} is the string generated by {{ic|grub-mkpasswd_pbkdf2}}.<br />
<br />
Regenerate your configuration file. Your GRUB2 command line, boot parameters and all boot entries are now protected.<br />
<br />
This can be relaxed and further customized with more users as described in the "Security" part of [https://www.gnu.org/software/grub/manual/grub.html#Security the GRUB manual].<br />
<br />
==== Root Encryption ====<br />
<br />
To let GRUB2 automatically add the kernel parameters for root encryption,<br />
add {{ic|1=cryptdevice=/dev/yourdevice:label}} to {{ic|GRUB_CMDLINE_LINUX}} in {{ic|/etc/defaults/grub}}.<br />
<br />
Example with root mapped to {{ic|/dev/mapper/root}}:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:root"<br />
<br />
Also, disable the usage of UUIDs for the rootfs:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
Regenerate the configuration.<br />
<br />
=== Booting an ISO Directly From GRUB2 ===<br />
Edit {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} to add an entry for the target ISO. When finished, update the GRUB menu as with the usual {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} (as root).<br />
<br />
==== Arch ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk/partition number of the isofile. Also adjust the {{ic|img_dev}} line to match this same location. However, if booting the ISO from USB on a computer which also has one internal HDD, then it needs to be {{ic|hd0,Y}} with {{ic|sdbY}}, instead of {{ic|sdaY}}.}}<br />
<br />
menuentry "Archlinux-2011.08.19-netinstall-x86_64.iso" {<br />
set isofile="/archives/archlinux-2011.08.19-netinstall-x86_64.iso"<br />
loopback loop (hd0,7)$isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=ARCH_201108 img_dev=/dev/sda7 img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
<br />
==== Ubuntu ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk or partition number of the ISO file.}}<br />
<br />
menuentry "ubuntu-12.04-desktop-amd64.iso" {<br />
set isofile="/path/to/ubuntu-12.04-desktop-amd64.iso"<br />
loopback loop (hdX,Y)$isofile<br />
linux (loop)/casper/vmlinuz boot=casper iso-scan/filename=$isofile quiet noeject noprompt splash --<br />
initrd (loop)/casper/initrd.lz<br />
}<br />
<br />
== Using the command shell ==<br />
<br />
Since the MBR is too small to store all GRUB2 modules, only the menu and a few basic commands reside there. The majority of GRUB2 functionality remains in modules in {{ic|/boot/grub}}, which are inserted as needed. In error conditions (e.g. if the partition layout changes) GRUB2 may fail to boot. When this happens, a command shell may appear.<br />
<br />
GRUB2 offers multiple shells/prompts. If there is a problem reading the menu but the bootloader is able to find the disk, you will likely be dropped to the "normal" shell:<br />
sh:grub><br />
<br />
If there is a more serious problem (e.g. GRUB cannot find required files), you may instead be dropped to the "rescue" shell:<br />
grub rescue><br />
<br />
The rescue shell is a restricted subset of the normal shell, offering much less functionality. If dumped to the rescue shell, first try inserting the "normal" module, then starting the "normal" shell:<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
grub rescue> insmod (hdX,Y)/boot/grub/i386-pc/normal.mod<br />
rescue:grub> normal<br />
<br />
=== Pager support ===<br />
<br />
GRUB2 supports pager for reading commands that provide long output (like the help command). This works only in normal shell mode and not in rescue mode. To enable pager, in GRUB2 command shell type:<br />
sh:grub> set pager=1<br />
<br />
== GUI configuration tools ==<br />
<br />
Following package may be installed from [[AUR]]<br />
* [https://aur.archlinux.org/packages.php?ID=44020 grub-customizer] (requires gettext gksu gtkmm hicolor-icon-theme openssl)<br />
*:Customize the bootloader (GRUB2 or BURG)<br />
* [http://kde-apps.org/content/show.php?content=139643 grub2-editor] (requires kdelibs)<br />
*:A KDE4 control module for configuring the GRUB2 bootloader<br />
* [http://kde-apps.org/content/show.php?content=137886 kcm-grub2] (requires kdelibs python2-qt kdebindings-python)<br />
*:This Kcm module manages the most common settings of Grub2.<br />
* [http://sourceforge.net/projects/startup-manager/ startupmanager] (requires gnome-python imagemagick yelp python2 xorg-xrandr)<br />
*:GUI app for changing the settings of GRUB, GRUB2, Usplash and Splashy<br />
<br />
== parttool or legacy hide/unhide ==<br />
<br />
If you have a Windows 9x paradigm with hidden C:\ disks GRUB Legacy had the hide/unhide feature. In GRUB2 this has been replaced by {{ic|parttool}}. For example, to boot the third C:\ disk of three Windows 9x installations on the CLI enter the CLI and:<br />
parttool hd0,1 hidden+ boot-<br />
parttool hd0,2 hidden+ boot-<br />
parttool hd0,3 hidden- boot+<br />
set root=hd0,3<br />
chainloader +1<br />
boot<br />
<br />
== Using the rescue console ==<br />
<br />
See [[#Using the command shell]] first. If unable to activate the standard shell, one possible solution is to boot using a live CD or some other rescue disk to correct configuration errors and reinstall GRUB. However, such a boot disk is not always available (nor necessary); the rescue console is surprisingly robust.<br />
<br />
The available commands in GRUB rescue include {{ic|insmod}}, {{ic|ls}}, {{ic|set}}, and {{ic|unset}}. This example uses {{ic|set}} and {{ic|insmod}}. {{ic|set}} modifies variables and {{ic|insmod}} inserts new modules to add functionality.<br />
<br />
Before starting, the user must know the location of their {{ic|/boot}} partition (be it a separate partition, or a subdirectory under their root):<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
<br />
where X is the physical drive number and Y is the partition number.<br />
<br />
To expand console capabilities, insert the {{ic|linux}} module:<br />
grub rescue> insmod (hdX,Y)/boot/grub/linux.mod<br />
<br />
{{Note|With a separate boot partition, omit {{ic|/boot}} from the path, (i.e. type {{ic|1=set prefix=(hdX,Y)/grub}} and {{ic|insmod (hdX,Y)/grub/linux.mod}}).}}<br />
<br />
This introduces the {{ic|linux}} and {{ic|initrd}} commands, which should be familiar (see [[#Configuration]]).<br />
<br />
An example, booting Arch Linux:<br />
set root=(hd0,5)<br />
linux /boot/vmlinuz-linux root=/dev/sda5<br />
initrd /boot/initramfs-linux.img<br />
boot<br />
<br />
With a separate boot partition, again change the lines accordingly:<br />
set root=(hd0,5)<br />
linux /vmlinuz-linux root=/dev/sda6<br />
initrd /initramfs-linux.img<br />
boot<br />
<br />
After successfully booting the Arch Linux installation, users can correct {{ic|grub.cfg}} as needed and then reinstall GRUB2.<br />
<br />
to reinstall GRUB2 and fix the problem completely, changing {{ic|/dev/sda}} if needed. See [[#Bootloader installation]] for details.<br />
<br />
== Combining the use of UUIDs and basic scripting ==<br />
<br />
If you like the idea of using UUIDs to avoid unreliable BIOS mappings or are struggling with GRUB's syntax, here is an example boot menu item that uses UUIDs and a small script to direct GRUB to the proper disk partitions for your system. All you need to do is replace the UUIDs in the sample with the correct UUIDs for your system. The example applies to a system with a boot and root partition. You will obviously need to modify the GRUB configuration if you have additional partitions:<br />
<br />
menuentry "Arch Linux 64" {<br />
# Set the UUIDs for your boot and root partition respectively<br />
set the_boot_uuid=ece0448f-bb08-486d-9864-ac3271bd8d07<br />
set the_root_uuid=c55da16f-e2af-4603-9e0b-03f5f565ec4a<br />
<br />
# (Note: This may be the same as your boot partition)<br />
<br />
# Get the boot/root devices and set them in the root and grub_boot variables<br />
search --fs-uuid --no-floppy --set=root $the_root_uuid<br />
search --fs-uuid --no-floppy --set=grub_boot $the_boot_uuid<br />
<br />
# Check to see if boot and root are equal.<br />
# If they are, then append /boot to $grub_boot (Since $grub_boot is actually the root partition)<br />
if [ $the_boot_uuid == $the_root_uuid] ; then<br />
set grub_boot=$grub_boot/boot<br />
fi<br />
<br />
# $grub_boot now points to the correct location, so the following will properly find the kernel and initrd<br />
linux ($grub_boot)/vmlinuz-linux root=/dev/disk/by-uuid/$uuid_os_root ro<br />
initrd ($grub_boot)/initramfs-linux.img<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
Any troubleshooting should be added here.<br />
<br />
=== Enable GRUB2 debug messages ===<br />
<br />
Add:<br />
<br />
set pager=1<br />
set debug=all<br />
<br />
to {{ic|grub.cfg}}.<br />
<br />
=== Correct GRUB2 No Suitable Mode Found Error ===<br />
<br />
If you get this error when booting any menuentry:<br />
<br />
error: no suitable mode found<br />
Booting however<br />
<br />
Then you need to initialize GRUB2 graphical terminal ({{ic|gfxterm}}) with proper video mode ({{ic|gfxmode}}) in GRUB2. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload'. In case of UEFI systems, if the GRUB2 video mode is not initialized, no kernel boot messages will be shown in the terminal (atleast until KMS kicks in).<br />
<br />
Copy {{ic|/usr/share/grub/unicode.pf2}} to ${GRUB2_PREFIX_DIR} ({{ic|/boot/grub/}} in case of BIOS and UEFI systems). If GRUB2 UEFI was installed with {{ic|1=--boot-directory=/boot/efi/EFI}} set, then the directory is {{ic|/boot/efi/EFI/grub/}}:<br />
<br />
# cp /usr/share/grub/unicode.pf2 ${GRUB2_PREFIX_DIR}<br />
<br />
If {{ic|/usr/share/grub/unicode.pf2}} does not exist, install {{Pkg|bdf-unifont}}, create the {{ic|unifont.pf2}} file and then copy it to {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}:<br />
<br />
# grub-mkfont -o unicode.pf2 /usr/share/fonts/misc/unifont.bdf<br />
<br />
Then, in the {{ic|grub.cfg}} file, add the following lines to enable GRUB2 to pass the video mode correctly to the kernel, without of which you will only get a black screen (no output) but booting (actually) proceeds successfully without any system hang.<br />
<br />
BIOS systems:<br />
<br />
insmod vbe<br />
<br />
UEFI systems:<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
<br />
After that add the following code (common to both BIOS and UEFI):<br />
<br />
insmod font<br />
<br />
if loadfont ${prefix}/fonts/unicode.pf2<br />
then<br />
insmod gfxterm<br />
set gfxmode=auto<br />
set gfxpayload=keep<br />
terminal_output gfxterm<br />
fi<br />
<br />
As you can see for gfxterm (graphical terminal) to function properly, {{ic|unicode.pf2}} font file should exist in {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}.<br />
<br />
=== msdos-style error message ===<br />
<br />
grub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding won't be possible!<br />
grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.<br />
However, blocklists are UNRELIABLE and its use is discouraged.<br />
grub-setup: error: If you really want blocklists, use --force.<br />
<br />
This error may occur when you try installing GRUB2 in a VMware container. Read more about it [https://bbs.archlinux.org/viewtopic.php?pid=581760#p581760 here]. It happens when the first partition starts just after the MBR (block 63), without the usual space of 1 MiB (2048 blocks) before the first partition. Read [[#MBR_aka_msdos_partitioning_specific_instructions]]<br />
<br />
=== UEFI GRUB2 drops to shell ===<br />
<br />
If GRUB loads but drops you into the rescue shell with no errors, it may be because of a missing or misplaced {{ic|grub.cfg}}. This will happen if GRUB2 UEFI was installed with {{ic|--boot-directory}} and {{ic|grub.cfg}} is missing OR if the partition number of the boot partition changed (which is hard-coded into the {{ic|grubx64.efi}} file).<br />
<br />
=== UEFI GRUB2 not loaded ===<br />
In some cases the EFI may fail to load GRUB correctly. Provided everything is set up correctly, the output of:<br />
efibootmgr -v<br />
might look something like this:<br />
BootCurrent: 0000<br />
Timeout: 3 seconds<br />
BootOrder: 0000,0001,0002<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\efi\grub\grub.efi)<br />
Boot0001* Shell HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\EfiShell.efi)<br />
Boot0002* Festplatte BIOS(2,0,00)P0: SAMSUNG HD204UI<br />
If everything works correctly, the EFI would now automatically load GRUB.<br />
<br />
If the screen only goes black for a second and the next boot option is tried afterwards, according to [https://bbs.archlinux.org/viewtopic.php?pid=981560#p981560 this post], moving GRUB to the partition root can help. The boot option has to be deleted and recreated afterwards. The entry for GRUB should look like this then:<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\grub.efi)<br />
<br />
=== Invalid signature ===<br />
If trying to boot Windows results in an "invalid signature" error, e.g. after reconfiguring partitions or adding additional hard drives, (re)move GRUB's device configuration and let it reconfigure:<br />
# mv /boot/grub/device.map /boot/grub/device.map-old<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
{{ic|grub-mkconfig}} should now mention all found boot options, including Windows. If it works, remove {{ic|/boot/grub/device.map-old}}.<br />
<br />
=== Restore GRUB Legacy ===<br />
<br />
* Move GRUB2 files out of the way:<br />
<br />
# mv /boot/grub /boot/grub.nonfunctional<br />
<br />
* Copy GRUB Legacy back to {{ic|/boot}}:<br />
<br />
# cp -af /boot/grub-legacy /boot/grub<br />
<br />
* Replace MBR and next 62 sectors of sda with backed up copy<br />
<br />
{{Warning|This command also restores the partition table, so be careful of overwriting a modified partition table with the old one. It '''will''' mess up your system.}}<br />
<br />
# dd if=/path/to/backup/first-sectors of=/dev/sdX bs=512 count=1<br />
<br />
A safer way is to restore only the MBR boot code use:<br />
<br />
# dd if=/path/to/backup/mbr-boot-code of=/dev/sdX bs=446 count=1<br />
<br />
== References ==<br />
<br />
# Official GRUB2 Manual - https://www.gnu.org/software/grub/manual/grub.html<br />
# Ubuntu wiki page for GRUB2 - https://help.ubuntu.com/community/Grub2<br />
# GRUB2 wiki page describing steps to compile for UEFI systems - https://help.ubuntu.com/community/UEFIBooting<br />
# Wikipedia's page on [[Wikipedia:BIOS Boot partition|BIOS Boot partition]]<br />
<br />
== External Links ==<br />
<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_bios.sh A Linux Bash Shell script to compile and install GRUB(2) for BIOS from BZR Source]<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_uefi.sh A Linux Bash Shell script to compile and install GRUB(2) for UEFI from BZR Source]</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=GRUB&diff=214411GRUB2012-07-24T06:47:46Z<p>Lfxgroove: /* Boot Microsoft Windows installed in BIOS-MBR mode */ Changed to a warning instead</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[cs:GRUB2]]<br />
[[es:GRUB2]]<br />
[[fr:GRUB2]]<br />
[[id:GRUB2]]<br />
[[it:GRUB2]]<br />
[[ru:GRUB2]]<br />
[[tr:GRUB2]]<br />
[[zh-CN:GRUB2]]<br />
[[zh-TW:GRUB2]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers various aspects of the next generation of the GRand Unified Bootloader (GRUB2).}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Burg}} - Burg is a brand-new boot loader based on GRUB2. It uses a new object format which allows it to be built in a wider range of OS, including Linux, Windows, OS X, Solaris, FreeBSD, etc. It also has a highly configurable menu system which works in both text and graphic mode. <br />
{{Article summary heading|Resources}}<br />
{{Article summary link|GNU GRUB -- GNU Project|https://www.gnu.org/software/grub/}}<br />
{{Article summary end}}<br />
<br />
[https://www.gnu.org/software/grub/ GRUB2] is the next generation of the GRand Unified Bootloader (GRUB). GRUB2 is derived from [http://www.nongnu.org/pupa/ PUPA] which was a research project to investigate the next generation of GRUB. GRUB2 has been rewritten from scratch to clean up everything and provide modularity and portability [https://www.gnu.org/software/grub/grub-faq.en.html#q1].<br />
<br />
In brief, the ''bootloader'' is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the Linux kernel. The kernel, in turn, initializes the rest of the operating system.<br />
<br />
== Preface ==<br />
Here is some information needs to be clarified:<br />
* The name ''GRUB'' officially refers to version ''2'' of the software, see [https://www.gnu.org/software/grub/]. If you are looking for the article on the legacy version, see [[GRUB Legacy]].<br />
<br />
* [[GRUB Legacy]] (i.e. version 0.9x) is considered legacy by upstream and is being replaced by GRUB2 and [[Syslinux]] in Arch Linux. See the news [https://www.archlinux.org/news/grub-legacy-no-longer-supported/ here]. Upstream recommends GRUB2 >=1.99 over GRUB Legacy, even for current GRUB Legacy users.<br />
<br />
* The [[Archboot]] ISO's installer script supports {{Pkg|grub-bios}} and {{Pkg|grub-efi-x86_64}} installation. The official installer script AIF (Arch Installation Framework) does not support GRUB(2) yet.<br />
<br />
* From 1.99-6 onwards, GRUB2 supports [[Btrfs]] as root (without a separate {{ic|/boot}} filesystem) compressed with either zlib or LZO.<br />
<br />
* For GRUB2 UEFI info, it is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this page.<br />
<br />
=== Notes for current GRUB Legacy users ===<br />
* Although GRUB legacy will not be removed from your system and will stay fully functional, you should consider upgrading to GRUB version 2.x, or one of the other supported bootloaders.<br />
<br />
* Upgrade from [[GRUB Legacy]] to [[GRUB]](2) is the much same as installing GRUB from a running Arch Linux which is covered [[#From a running Arch Linux|below]].<br />
<br />
* There are differences in the commands of GRUB and GRUB2. Familiarize yourself with [https://www.gnu.org/software/grub/manual/grub.html#Commands GRUB2 commands] before proceeding (e.g. "find" has been replaced with "search").<br />
<br />
* GRUB2 is now ''modular'' and no longer requires "stage 1.5". As a result, the bootloader itself is limited -- modules are loaded from the hard drive as needed to expand functionality (e.g. for [[LVM]] or RAID support).<br />
<br />
* Device naming has changed between GRUB and GRUB2. Partitions are numbered from 1 instead of 0 while drives are still numbered from 0, and prefixed with partition-table type. For example, {{ic|/dev/sda1}} would be referred to as {{ic|(hd0,msdos1)}} (for MBR) or {{ic|(hd0,gpt1)}} (for GPT) using GRUB2.<br />
<br />
=== Preliminary Requirements for GRUB2 ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== [[GPT]] specific instructions =====<br />
<br />
GRUB2 in BIOS-GPT configuration requires a BIOS Boot Partition to embed its {{ic|core.img}} in the absence of post-MBR gap in GPT partitioned systems (which is taken over by the GPT Primary Header and Primary Partition table). This partition is used by GRUB2 only in BIOS-GPT setups. No such partition type exists in case of MBR partitioning (at least not for GRUB2). This partition is also not required if the system is UEFI based, as no embedding of bootsectors takes place in that case. Syslinux does not require this partition.<br />
<br />
For a BIOS-GPT configuration, create a 2 MiB partition using cgdisk or GNU Parted with no filesystem. The location of the partition in the partition table does not matter but it should be within the first 2 TiB region of the disk. It is advisable to put it somewhere in the beginning of the disk before the {{ic|/boot}} partition. Set the partition type to "EF02" in cgdisk or {{ic|set <BOOT_PART_NUM> bios_grub on}} in GNU Parted.<br />
<br />
{{Note|This partition should be created before {{ic|grub-install}} or {{ic|grub-setup}} is run or before the '''Install Bootloader''' step of the Archlinux installer (if GRUB2 BIOS is selected as bootloader).}}<br />
<br />
===== [[MBR]] aka msdos partitioning specific instructions =====<br />
<br />
Usually the post-MBR gap (after the 512 byte MBR region and before the start of the 1st partition) in many MBR (or msdos disklabel) partitioned systems is 32 KiB when DOS compatibility cylinder alignment issues are satisfied in the partition table. However a post-MBR gap of about 1 to 2 MiB is recommended to provide sufficient room for embedding GRUB2's {{ic|core.img}} ({{bug|24103}}). It is advisable to use a partitioner which supports 1 MiB partition alignment to obtain this space as well as satisfy other non-512 byte sector issues (which are unrelated to embedding of {{ic|core.img}}).<br />
<br />
If you do not dual-boot with MS Windows (any version) in BIOS systems, it is advisable to switch to GPT partitioning - [[GUID_Partition_Table#Convert_from_MBR_to_GPT]]<br />
<br />
{{Note|Create the 2MiB partition mentioned above BEFORE you convert to GPT. If you do not, gparted will not resize your boot partition to allow its creation, and when you reboot GRUB2 will not know where to look.}}<br />
<br />
==== UEFI systems ====<br />
<br />
===== Create and Mount the UEFI SYSTEM PARTITION =====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
Follow [[Unified_Extensible_Firmware_Interface#Create_an_UEFI_System_Partition_in_Linux]] for instructions on creating a UEFI SYSTEM PARTITION. Then mount the UEFI SYSTEM PARTITION at {{ic|/boot/efi}}. If you have mounted the UEFISYS partition in some other mountpoint, replace {{ic|/boot/efi}} in the below instructions with that mountpoint:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat <UEFISYS_PART_DEVICE> /boot/efi<br />
<br />
Create a <UEFI_SYSTEM_PARTITION>{{ic|/EFI}} directory, if it does not exist:<br />
<br />
# mkdir -p /boot/efi/EFI<br />
<br />
== Installation ==<br />
<br />
=== During Arch Linux installation ===<br />
<br />
* Skip the '''Install Bootloader''' step and exit the installer.<br />
* Configure the network:<br />
# aif -p partial-configure-network<br />
This will bring up a prompt; put in the network interface to use, (e.g., {{ic|eth0}}) and use DHCP for easy configuration.<br />
* If you did not configure the installed system's {{ic|/etc/resolv.conf}} file during installation (for instance, if you plan to let DHCP generate it later), you will need to copy the one generated by AIF when it configured the network:<br />
# cp /etc/resolv.conf /mnt/etc/resolv.conf<br />
* If you run into network issues in the pacman update step below, you may have needed to install the {{Pkg|net-tools}} package.<br />
* Check and see if the {{ic|dm_mod}} module is loaded. If it is not, load it manually:<br />
# lsmod | grep dm_mod<br />
# modprobe dm-mod<br />
{{Note|This is necessary at this point, and cannot be postponed after the chroot. If you try to use modprobe in a chroot environment that has a later kernel version from that of the installing device (at the time of writing, 2.6.33), modprobe will fail. This happens routinely using the Arch "net" installations.}}<br />
* From the installer's live shell, chroot to the installed system:<br />
# mount -o bind /dev /mnt/dev<br />
# mount -t proc /proc /mnt/proc/<br />
# mount -t sysfs /sys /mnt/sys/<br />
# chroot /mnt bash<br />
* Refresh the package list (with an extra {{ic|-y}} flag to force a refresh of all package lists even if they appear to be up to date):<br />
# pacman -Syy<br />
* Install the GRUB2 package as mentioned in the section [[#From a running Arch Linux]] (Note that the {{ic|dm-mod}} module has already been loaded, no need to do that again).<br />
<br />
=== From a running Arch Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Backup Important Data =====<br />
<br />
Although a GRUB(2) installation should run smoothly, it is strongly recommended to keep the GRUB Legacy files before installing {{Pkg|grub-bios}}.<br />
<br />
# mv /boot/grub /boot/grub-legacy<br />
<br />
Backup the MBR which contains the boot code and partition table (Replace {{ic|/dev/sd'''X'''}} with your actual disk path)<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/mbr_backup bs=512 count=1<br />
<br />
Only 446 bytes of the MBR contain boot code, the next 64 contain the partition table. If you do not want to overwrite your partition table when restoring, it is strongly advised to backup only the MBR boot code:<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/bootcode_backup bs=446 count=1<br />
<br />
If unable to install GRUB2 correctly, see [[GRUB2#Restore_GRUB_Legacy]].<br />
<br />
===== Install grub-bios package =====<br />
<br />
The GRUB(2) packages can be installed with pacman (and will replace {{Pkg|grub-legacy}} or {{Pkg|grub}}, if it is installed):<br />
<br />
# pacman -S grub-bios<br />
<br />
{{Note|Simply installing the package won't update the {{ic|/boot/grub/i386-pc/core.img}} file and the GRUB(2) modules in {{ic|/boot/grub/i386-pc}}. You need to update them manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm_mod<br />
<br />
===== Install grub-bios boot files =====<br />
<br />
There are 3 ways to install GRUB(2) boot files in BIOS booting:<br />
*[[#Install_to_440-byte_MBR_boot_code_region]] (recommended) , <br />
*[[#Install_to_Partition_or_Partitionless_Disk]] (not recommended),<br />
*[[#Generate_core.img_alone]] (safest method, but requires another BIOS bootloader like [[grub-legacy]] or [[syslinux]] to be installed to chainload {{ic|/boot/grub/i386-pc/core.img}}). <br />
<br />
====== Install to 440-byte MBR boot code region ======<br />
<br />
To setup {{ic|grub-bios}} in the 440-byte Master Boot Record boot code region, populate the {{ic|/boot/grub}} directory, generate the {{ic|/boot/grub/i386-pc/core.img}} file, and embed it in the 32 KiB (minimum size - varies depending on partition alignment) post-MBR gap (MBR disks) or in BIOS Boot Partition (GPT disks), run:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
where {{ic|/dev/sda}} is the destination of the installation (in this case the MBR of the first SATA disk). If you use [[LVM]] for your {{ic|/boot}}, you can install GRUB2 on multiple physical disks. <br />
<br />
The {{ic|--no-floppy}} tells {{ic|grub-bios}} utilities not to search for any floppy devices which reduces the overall execution time of {{ic|grub-install}} on many systems (it will also prevent the issue below from occurring). Otherwise you get an error that looks like this:<br />
<br />
grub-probe: error: Cannot get the real path of '/dev/fd0'<br />
Auto-detection of a filesystem module failed.<br />
Please specify the module with the option '--modules' explicitly.<br />
<br />
{{Note|{{ic|--no-floppy}} has been removed from {{ic|grub-install}} in 2.00~beta2 upstream release, and replaced with {{ic|--allow-floppy}}.}}<br />
<br />
{{Warning|Make sure to check the {{ic|/boot}} directory if you use the latter. Sometimes the {{ic| boot-directory}} parameter creates another {{ic|/boot}} folder inside of {{ic|/boot}}. A wrong install would look like: {{ic|/boot/boot/grub/}}.}}<br />
<br />
====== Install to Partition or Partitionless Disk ======<br />
<br />
{{Note|{{ic|grub-bios}} (any version - including upstream Bazaar repo) does not encourage installation to a partition boot sector or a partitionless disk like GRUB Legacy or syslinux does. This kind of setup is prone to breakage, especially during updates, and is not supported by Arch devs.}}<br />
<br />
To set up {{ic|grub-bios}} to a partition boot sector, to a partitionless disk (also called superfloppy) or to a floppy disk, run (using for example {{ic|/dev/sdaX}} as the {{ic|/boot}} partition):<br />
<br />
# chattr -i /boot/grub/i386-pc/core.img<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --force --debug /dev/sdaX<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# chattr +i /boot/grub/i386-pc/core.img<br />
<br />
You need to use the {{ic|--force}} option to allow usage of blocklists and should not use {{ic|1=--grub-setup=/bin/true}} (which is similar to simply generating {{ic|core.img}}).<br />
<br />
{{ic|grub-install}} will give out warnings like which should give you the idea of what might go wrong with this approach:<br />
<br />
/sbin/grub-setup: warn: Attempting to install GRUB to a partitionless disk or to a partition. This is a BAD idea.<br />
/sbin/grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. <br />
However, blocklists are UNRELIABLE and their use is discouraged.<br />
<br />
Without {{ic|--force}} you may get the below error and {{ic|grub-setup}} will not setup its boot code in the partition boot sector:<br />
<br />
/sbin/grub-setup: error: will not proceed with blocklists<br />
<br />
With {{ic|--force}} you should get:<br />
<br />
Installation finished. No error reported.<br />
<br />
The reason why {{ic|grub-setup}} does not by default allow this is because in case of partition or a partitionless disk is that {{ic|grub-bios}} relies on embedded blocklists in the partition bootsector to locate the {{ic|/boot/grub/i386-pc/core.img}} file and the prefix dir {{ic|/boot/grub}}. The sector locations of {{ic|core.img}} may change whenever the filesystem in the partition is being altered (files copied, deleted etc.). For more info see https://bugzilla.redhat.com/show_bug.cgi?id=728742 and https://bugzilla.redhat.com/show_bug.cgi?id=730915.<br />
<br />
The workaround for this is to set the immutable flag on {{ic|/boot/grub/i386-pc/core.img}} (using chattr command as mentioned above) so that the sector locations of the {{ic|core.img}} file in the disk is not altered. The immutable flag on {{ic|/boot/grub/i386-pc/core.img}} needs to be set only if {{ic|grub-bios}} is installed to a partition boot sector or a partitionless disk, not in case of installtion to MBR or simple generation of {{ic|core.img}} without embedding any bootsector (mentioned above).<br />
<br />
====== Generate core.img alone ======<br />
<br />
To populate the {{ic|/boot/grub}} directory and generate a {{ic|/boot/grub/i386-pc/core.img}} file '''without''' embedding any {{ic|grub-bios}} bootsector code in the MBR, post-MBR region, or the partition bootsector, add {{ic|1=--grub-setup=/bin/true}} to {{ic|grub-install}}:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --grub-setup=/bin/true --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
You can then chainload GRUB2's {{ic|core.img}} from GRUB Legacy or syslinux as a Linux kernel or a multiboot kernel.<br />
<br />
===== Generate GRUB2 BIOS Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|/boot/grub/grub.cfg}}, NOT {{ic|/boot/grub/i386-pc/grub.cfg}}.}}<br />
<br />
If grub2 complains about "no suitable mode found" while booting, go to [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
If {{ic|grub-mkconfig}} fails, convert your {{ic|/boot/grub/menu.lst}} file to {{ic|/boot/grub/grub.cfg}} using:<br />
<br />
# grub-menulst2cfg /boot/grub/menu.lst /boot/grub/grub.cfg<br />
<br />
For example:<br />
<br />
{{hc|/boot/grub/menu.lst|<nowiki><br />
default=0<br />
timeout=5<br />
<br />
title Arch Linux Stock Kernel<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux.img<br />
<br />
title Arch Linux Stock Kernel Fallback<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux-fallback.img<br />
</nowiki>}}<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set default='0'; if [ x"$default" = xsaved ]; then load_env; set default="$saved_entry"; fi<br />
set timeout=5<br />
<br />
menuentry 'Arch Linux Stock Kernel' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux.img' '/initramfs-linux.img'<br />
<br />
}<br />
<br />
menuentry 'Arch Linux Stock Kernel Fallback' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux-fallback.img' '/initramfs-linux-fallback.img'<br />
}<br />
</nowiki>}}<br />
<br />
If you forgot to create a GRUB2 {{ic|/boot/grub/grub.cfg}} config file and simply rebooted into GRUB2 Command Shell, type:<br />
<br />
sh:grub> insmod legacycfg<br />
sh:grub> legacy_configfile ${prefix}/menu.lst<br />
<br />
Boot into Arch and re-create the proper GRUB2 {{ic|/boot/grub/grub.cfg}} config file.<br />
<br />
{{Note|This option works only in BIOS systems, not in UEFI systems.}}<br />
<br />
===== Multiboot in BIOS =====<br />
<br />
====== Boot Microsoft Windows installed in BIOS-MBR mode ======<br />
<br />
{{Note|GRUB2 supports booting {{ic|bootmgr}} directly and chainload of partition boot sector is no longer required to boot Windows in a BIOS-MBR setup.}}<br />
<br />
{{Warning|Take note that it is the SYSTEM PARTITION that has the bootmgr, not your "real" windows partition, ie: when showing all UUID's with blkid it is the partition with LABEL&#61;"SYSTEM RESERVED" which is only about 100 mb big much like the boot partition for arch.}}<br />
<br />
Find the UUID of the NTFS filesystem of the Windows's SYSTEM PARTITION where the {{ic|bootmgr}} and its files reside. For example, if Windows {{ic|bootmgr}} exists at {{ic|/media/Windows/bootmgr}}:<br />
<br />
# grub-probe --target=fs_uuid /media/Windows/bootmgr<br />
69B235F6749E84CE<br />
<br />
Then, add the below code to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} and regenerate {{ic|grub.cfg}} with {{ic|grub-mkconfig}} as explained above to boot Windows (Vista, 7 or 8) installed in BIOS-MBR mode:<br />
<br />
<pre><br />
menuentry "Microsoft Windows 7 BIOS-MBR" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}</pre><br />
<br />
For Windows XP:<br />
<br />
menuentry "Microsoft Windows XP" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /ntldr<br />
}<br />
<br />
==== UEFI systems ====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
===== Install grub-uefi package =====<br />
<br />
{{Note|Unless specified as EFI 1.x , EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitely, the instructions are general and not Mac specific. Some of them may not work or may be different in Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one UEFI Specification version and is therefore not a standard UEFI firmware.}}<br />
<br />
GRUB2 UEFI bootloader is available in Arch Linux only from version 1.99~rc1. To install, first [[Unified_Extensible_Firmware_Interface#Detecting_UEFI_Firmware_Arch|detect which UEFI firmware arch]] you have (either x86_64 or i386).<br />
<br />
Depending on that, install the appropriate package<br />
<br />
For 64-bit aka x86_64 UEFI firmware:<br />
# pacman -S grub-efi-x86_64<br />
<br />
For 32-bit aka i386 UEFI firmware:<br />
# pacman -S grub-efi-i386<br />
<br />
{{Note|Simply installing the package will not update the {{ic|grub.efi}} file and the GRUB(2) modules in the UEFI System Partition. You need to do this manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm-mod<br />
<br />
===== Install grub-uefi boot files =====<br />
<br />
====== Install to UEFI SYSTEM PARTITION ======<br />
<br />
{{Note|The below commands assume you are using {{ic|grub-efi-x86_64}} (for {{ic|grub-efi-i386}} replace {{ic|x86_64}} with {{ic|i386}} in the below commands).}}<br />
<br />
The UEFI system partition will need to be mounted at {{ic|/boot/efi/}} for the GRUB2 install script to detect it:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat /dev/sdXY /boot/efi<br />
<br />
Install GRUB UEFI application to {{ic|/boot/efi/EFI/arch_grub}} and its modules to {{ic|/boot/grub/x86_64-efi}} (recommended) using:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot --recheck --debug<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
If you want to install grub2 modules and {{ic|grub.cfg}} at the directory {{ic|/boot/efi/EFI/grub}} and the {{ic|grubx64.efi}} application at {{ic|/boot/efi/EFI/arch_grub}} use:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot/efi/EFI --recheck --debug<br />
# mkdir -p /boot/efi/EFI/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/efi/EFI/grub/locale/en.mo<br />
<br />
In this case {{ic|grub-efi-x86_64}} will be installed into {{ic|/boot/grub}}, making the behavior consistent with the BIOS verion of GRUB2, but this is not recommended if you use both {{ic|grub-bios}} and {{ic|grub-efi-x86_64}} in your system, as this will overwrite {{ic|grub-bios }}modules in {{ic|/boot/grub}}.<br />
<br />
The {{ic|--efi-directory}} option mentions the mountpoint of UEFI SYSTEM PARTITION , {{ic|--bootloader-id}} mentions the name of the directory used to store the {{ic|grubx64.efi}} file and {{ic|--boot-directory}} mentions the directory wherein the actual modules will be installed (and into which {{ic|grub.cfg}} should be created).<br />
<br />
The actual paths are:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi<br />
<br />
<boot-directory>/grub/x86_64-efi/<all modules, grub.efi, core.efi, grub.cfg><br />
<br />
{{Note|the {{ic|--bootloader-id}} option does not change {{ic|<boot-directory>/grub}}, i.e. you cannot install the modules to {{ic|<boot-directory>/<bootloader-id>}}, the path is hard-coded to be {{ic|<boot-directory>/grub}}.}}<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == <boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
The {{ic|<nowiki><efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi</nowiki>}} is an exact copy of {{ic|<nowiki><boot-directory>/grub/x86_64-efi/core.efi</nowiki>}}.<br />
<br />
{{Note|In GRUB2 2.00~beta4, the {{ic|grub-install}} option {{ic|--efi-directory}} replaces {{ic|--root-directory}} and the latter is deprecated.}}<br />
{{Note|The options {{ic|--efi-directory}} and {{ic|--bootloader-id}} are specific to GRUB2 UEFI.}}<br />
<br />
In all the cases the UEFI SYSTEM PARTITION should be mounted for {{ic|grub-install}} to install {{ic|grubx64.efi}} in it, which will be launched by the firmware (using the {{ic|efibootmgr}} created boot entry in non-Mac systems).<br />
<br />
If you notice carefully, there is no <device_path> option (Eg: {{ic|/dev/sda}}) at the end of the {{ic|grub-install}} command unlike the case of setting up GRUB2 for BIOS systems. Any <device_path> provided will be ignored by the install script as UEFI bootloaders do not use MBR or Partition boot sectors at all.<br />
<br />
You may now be able to UEFI boot your system by creating a {{ic|grub.cfg}} file by following [[#Generate_GRUB2_UEFI_Config_file]] and [[#Create_GRUB2_entry_in_the_Firmware_Boot_Manager]].<br />
<br />
===== Create GRUB2 entry in the Firmware Boot Manager =====<br />
<br />
====== Non-Mac UEFI systems ======<br />
<br />
{{ic|grub-install}} will ensure that {{ic|/boot/efi/EFI/arch_grub/grubx64.efi}} is launched by default if it detects {{ic|efibootmgr}} and if it is able to access UEFI Runtime Services. Follow [[Unified_Extensible_Firmware_Interface#efibootmgr]] for more info.<br />
<br />
If you have problems running GRUB2 in UEFI mode you can try the following (worked on an ASUS Z68 mainboard):<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/tools/shellx64.efi<br />
<br />
After this launch the UEFI Shell from the UEFI setup/menu (in ASUS UEFI BIOS, switch to advanced mode, press Exit in the top right corner and choose "Launch EFI shell from filesystem device"). The GRUB2 menu will show up and you can boot into your system. Afterwards you can use efibootmgr to setup a menu entry (see above).<br />
<br />
====== Apple Mac EFI systems ======<br />
<br />
{{Note|TODO: GRUB upstream Bazaar mactel branch http://bzr.savannah.gnu.org/lh/grub/branches/mactel/changes. No further update from grub developers.}}<br />
{{Note|TODO: Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}. Requires more testing.}}<br />
<br />
Use bless command from within Mac OS X to set {{ic|grubx64.efi}} as the default boot option. You can also boot from the Mac OS X install disc and launch a Terminal there if you only have Linux installed. In the Terminal, create a directory and mount the EFI System Partition:<br />
<br />
# cd /Volumes<br />
# mkdir efi<br />
# mount -t msdos /dev/disk0s1 /Volumes/efi<br />
<br />
Then run bless on {{ic|grub.efi}} and on the EFI partition to set them as the default boot options.<br />
<br />
# bless --folder=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
# bless --mount=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
<br />
More info at https://help.ubuntu.com/community/UEFIBooting#Apple_Mac_EFI_systems_.28both_EFI_architecture.29.<br />
<br />
===== Generate GRUB2 UEFI Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o <boot-directory>/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|<boot-directory>/grub/grub.cfg}}, NOT {{ic|<boot-directory>/grub/x86_64-efi/grub.cfg}}.}}<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot/efi/EFI</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/efi/EFI/grub/grub.cfg<br />
<br />
This is independent of the value of {{ic|--bootloader-id}} option.<br />
<br />
If GRUB2 complains about "no suitable mode found" while booting, try [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
===== Create GRUB2 Standalone UEFI Application =====<br />
<br />
It is possible to create a {{ic|grubx64_standalone.efi}} application which has all the modules embeddded in a memdisk within the uefi application, thus removing the need for having a separate directory populated with all the GRUB2 uefi modules and other related files. This is done using the {{ic|grub-mkstandalone}} command which is included in {{Pkg|grub-common}} >= 1:1.99-6 package.<br />
<br />
The easiest way to do this would be with the install command already mentioned before, but specifying the modules to include. For example:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" <any extra files you want to include><br />
<br />
The {{ic|grubx64_standalone.efi}} file expects {{ic|grub.cfg}} to be within its $prefix which is {{ic|(memdisk)/boot/grub}}. The memdisk is embedded within the efi app. The {{ic|grub-mkstandlone}} script allow passing files to be included in the memdisk image to be as the arguments to the script (in <any extra files you want to include>).<br />
<br />
If you have the {{ic|grub.cfg}} at {{ic|/home/user/Desktop/grub.cfg}}, then create a temporary {{ic|/home/user/Desktop/boot/grub/}} directory, copy the {{ic|/home/user/Desktop/grub.cfg}} to {{ic|/home/user/Desktop/boot/grub/grub.cfg}}, cd into {{ic|/home/user/Desktop/boot/grub/}} and run:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" "boot/grub/grub.cfg"<br />
<br />
The reason to cd into {{ic|/home/user/Desktop/boot/grub/}} and to pass the file path as {{ic|boot/grub/grub.cfg}} (notice the lack of a leading slash - boot/ vs /boot/ ) is because {{ic|dir1/dir2/file}} is included as {{ic|(memdisk)/dir1/dir2/file}} by the {{ic|grub-mkstandalone}} script. <br />
<br />
If you pass {{ic|/home/user/Desktop/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/grub.cfg}}. If you pass {{ic|/home/user/Desktop/boot/grub/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/boot/grub/grub.cfg}}. That is the reason for cd'ing into {{ic|/home/user/Desktop/boot/grub/}} and passing {{ic|boot/grub/grub.cfg}}, to include the file as {{ic|(memdisk)/boot/grub/grub.cfg}}, which is what {{ic|grub.efi}} expects the file to be.<br />
<br />
You need to create an UEFI Boot Manager entry for {{ic|/boot/efi/EFI/arch_grub/grubx64_standalone.efi}} using {{ic|efibootmgr}}. Follow [[#Create GRUB2 entry in the Firmware Boot Manager]].<br />
<br />
===== Multiboot in UEFI =====<br />
<br />
====== Chainload Microsoft Windows x86_64 UEFI-GPT ======<br />
<br />
Find the UUID of the FAT32 filesystem in the UEFI SYSTEM PARTITION where the Windows UEFI Bootloader files reside. For example, if Windows {{ic|bootmgfw.efi}} exists at {{ic|/boot/efi/EFI/Microsoft/Boot/bootmgfw.efi}} (ignore the upper-lower case differences since that is immaterial in FAT filesystem):<br />
<br />
# grub-probe --target=fs_uuid /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
1ce5-7f28<br />
<br />
# grub-probe --target=hints_string /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1<br />
<br />
Then, add this code to {{ic|/boot/grub/grub.cfg}} OR {{ic|/boot/efi/EFI/grub/grub.cfg}} to chainload Windows x86_64 (Vista SP1+, 7 or 8) installed in UEFI-GPT mode:<br />
<br />
menuentry "Microsoft Windows x86_64 UEFI-GPT" {<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1 1ce5-7f28<br />
chainloader /efi/Microsoft/Boot/bootmgfw.efi<br />
}<br />
<br />
== Configuration ==<br />
<br />
You can also choose to automatically generate or manually edit {{ic|grub.cfg}}.<br />
<br />
{{Note|For EFI systems, if GRUB2 was installed with the {{ic|--boot-directory}} option set, the {{ic|grub.cfg}} file must be placed in the same directory as {{ic|grubx64.efi}}. Otherwise, the {{ic|grub.cfg}} file goes in {{ic|/boot/grub/}}, just like in the BIOS version of GRUB2.}}<br />
<br />
{{Note|Here is a quite complete description of how to configure GRUB2: http://members.iinet.net/~herman546/p20/GRUB2%20Configuration%20File%20Commands.html }}<br />
<br />
=== Automatically generating using grub-mkconfig (Recommended) ===<br />
<br />
The GRUB2 {{ic|menu.lst}} equivalent configuration files are {{ic|/etc/default/grub}} and {{ic|/etc/grub.d/*}}. {{ic|grub-mkconfig}} uses these files to generate {{ic|grub.cfg}}. By default the script outputs to stdout. To generate a {{ic|grub.cfg}} file run the command:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{ic|/etc/grub.d/10_linux}} is set to automatically add menu items for Arch linux that work out of the box, to any generated configuration. Other operating systems may need to be added manually to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}}<br />
<br />
==== Additional arguments ====<br />
<br />
To pass custom additional arguments to the Linux image, you can set the {{ic|GRUB_CMDLINE_LINUX}} variable in {{ic|/etc/default/grub}}. This is analogous to adding commands to the kernel line in GRUB Legacy.<br />
<br />
For example, use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/sdaX"</nowiki>}} where {{ic|sda'''X'''}} is your swap partition to enable resume after hibernation.<br />
<br />
You can also use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/disk/by-uuid/${swap_uuid}"</nowiki>}}, where {{ic|${swap_uuid} }} is the [[Persistent_block_device_naming|UUID]] of your swap partition.<br />
<br />
Users who have replaced the default SysV init with [[systemd]] will want to add {{ic|<nowiki>init=/bin/systemd</nowiki>}} to their {{ic|<nowiki>GRUB_CMDLINE_LINUX</nowiki>}}.<br />
<br />
=== Manually creating grub.cfg ===<br />
<br />
{{Warning|Editing this file is strongly ''not'' recommended. The file is generated by the {{ic|grub-mkconfig}} command, and it is best to edit your {{ic|/etc/default/grub}} or one of the scripts in the {{ic|/etc/grub.d}} folder.}}<br />
<br />
A basic GRUB config file uses the following options<br />
* {{ic|(hdX,Y)}} is the partition {{ic|Y}} on disk {{ic|X}}, partition numbers starting at 1, disk numbers starting at 0<br />
* {{ic|1=set default=N}} is the default boot entry that is chosen after timeout for user action<br />
* {{ic|1=set timeout=M}} is the time {{ic|M}} to wait in seconds for a user selection before default is booted<br />
* {{ic|<nowiki>menuentry "title" {entry options}</nowiki>}} is a boot entry titled {{ic|title}}<br />
* {{ic|1=set root=(hdX,Y)}} sets the boot partition, where the kernel and GRUB modules are stored (boot need not be a separate partition, and may simply be a directory under the "root" partition ({{ic|/}})<br />
<br />
An example configuration:<br />
<br />
{{hc<br />
|/boot/grub/grub.cfg<br />
|<nowiki><br />
# Config file for GRUB2 - The GNU GRand Unified Bootloader<br />
# /boot/grub/grub.cfg<br />
<br />
# DEVICE NAME CONVERSIONS<br />
#<br />
# Linux Grub<br />
# -------------------------<br />
# /dev/fd0 (fd0)<br />
# /dev/sda (hd0)<br />
# /dev/sdb2 (hd1,2)<br />
# /dev/sda3 (hd0,3)<br />
#<br />
<br />
# Timeout for menu<br />
set timeout=5<br />
<br />
# Set default boot entry as Entry 0<br />
set default=0<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
set root=(hd0,1)<br />
linux /vmlinuz-linux root=/dev/sda3 ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
## (1) Windows<br />
#menuentry "Windows" {<br />
#set root=(hd0,3)<br />
#chainloader +1<br />
#}<br />
</nowiki>}}<br />
<br />
=== Dual-booting ===<br />
<br />
{{Note|If you want GRUB2 to automatically search for other systems, you may wish to install {{Pkg|os-prober}}.}}<br />
<br />
==== Using grub-mkconfig ====<br />
The best way to add other entries is editing the {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} . The entries in this file will be automatically added when running {{ic|grub-mkconfig}}.<br />
After adding the new lines, run:<br />
# grub-mkconfig -o /boot/grub/grub.cfg <br />
to generate an updated {{ic|grub.cfg}}.<br />
<br />
===== With GNU/Linux =====<br />
<br />
Assuming that the other distro is on partition {{ic|sda2}}:<br />
<br />
menuentry "Other Linux" {<br />
set root=(hd0,2)<br />
linux /boot/vmlinuz (add other options here as required)<br />
initrd /boot/initrd.img (if the other kernel uses/needs one)<br />
}<br />
<br />
===== With FreeBSD =====<br />
<br />
Requires that FreeBSD is installed on a single partition with UFS. Assuming it is installed on {{ic|sda4}}:<br />
<br />
menuentry "FreeBSD" {<br />
set root=(hd0,4)<br />
chainloader +1<br />
}<br />
<br />
===== With Windows =====<br />
<br />
This assumes that your Windows partition is {{ic|sda3}}.<br />
<br />
# (2) Windows XP<br />
menuentry "Windows XP" {<br />
set root=(hd0,3)<br />
chainloader (hd0,3)+1<br />
}<br />
<br />
If the Windows bootloader is on an entirely different hard drive than GRUB, it may be necessary to trick Windows into believing that it is the first hard drive. This was possible in GRUB Legacy with {{ic|map}} and is now done with {{ic|drivemap}}. Assuming GRUB is on {{ic|hd0}} and Windows is on {{ic|hd2}}, you need to add the following after {{ic|set root}}:<br />
<br />
drivemap -s hd0 hd2<br />
<br />
==== With Windows via EasyBCD and NeoGRUB ====<br />
<br />
Since EasyBCD's NeoGRUB currently does not understand the GRUB2 menu format, chainload to it by replacing the contents of your {{ic|C:\NST\menu.lst}} file with lines similar to the following:<br />
<br />
default 0<br />
timeout 1<br />
<br />
title Chainload into GRUB v2<br />
root (hd0,7)<br />
kernel /boot/grub/i386-pc/core.img<br />
<br />
===Visual Configuration===<br />
<br />
In GRUB2 it is possible, by default, to change the look of the menu. Make sure to initialize, if not done already, GRUB2 graphical terminal, gfxterm, with proper video mode, gfxmode, in GRUB2. This can be seen in the section [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]]. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload' so any visual configurations need this mode in order to be in effect.<br />
<br />
====Setting the framebuffer resolution ====<br />
<br />
GRUB2 can set the framebuffer for both GRUB2 itself and the kernel. The old {{ic|1=vga=}} way is deprecated. The preferred method is editing {{ic|/etc/default/grub}} as the following sample:<br />
<br />
GRUB_GFXMODE=1024x768x32<br />
GRUB_GFXPAYLOAD_LINUX=keep<br />
<br />
To generate the changes, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
The {{ic|gfxpayload}} property will make sure the kernel keeps the resolution.<br />
<br />
{{Note|If this example does not work for you try to replace {{ic|1=gfxmode="1024x768x32"}} by {{ic|1=vbemode="0x105"}}. Remember to replace the specified resolution with one suitable for your screen.}}<br />
{{Note|To show all the modes you can use {{ic|1=# hwinfo --framebuffer}} (hwinfo is available in [community]), while at GRUB2 prompt you can use the {{ic|1=vbeinfo}} command.}}<br />
<br />
If this method does not work for you, the deprecated {{ic|1=vga=}} method will still work. Just<br />
add it next to the {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="}} line in {{ic|/etc/default/grub}}<br />
for eg: {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vga=792"}} will give you a {{ic|1024x768}} resolution.<br />
<br />
You can choose one of these resolutions: {{ic|640×480}}, {{ic|800×600}}, {{ic|1024×768}}, {{ic|1280×1024}}, {{ic|1600×1200}}<br />
<br />
====915resolution hack ====<br />
<br />
Some times for Intel graphic adapters neither {{ic|1=# hwinfo --framebuffer}} nor {{ic|1=vbeinfo}} will show you the desired resolution. In this case you can use {{ic|915resolution}} hack. This hack will temporarily modify video BIOS and add needed resolution. See [http://915resolution.mango-lang.org/ 915resolution's home page]<br />
<br />
In the following I will proceed with the example for my system. Please adjust the recipe for your needs. First you need to find a video mode which will be modified later. For that, run {{ic|915resolution}} in GRUB2 command shell:<br />
915resolution -l<br />
The output will be something like:<br />
Intel 800/900 Series VBIOS Hack : version 0.5.3<br />
...<br />
Mode 30 : 640x480, 8 bits/pixel<br />
...<br />
Next, our purpose is to overwrite mode 30. (You can choose what ever mode you want.) In the file {{ic|/etc/grub.d/00_header}} just before the {{ic|set gfxmode&#61;${GRUB_GFXMODE}}} line insert:<br />
915resolution 30 1440 900<br />
Here we are overwriting the mode {{ic|30}} with {{ic|1440x900}} resolution. Lastly we need to set {{ic|GRUB_GFXMODE}} as described earlier, regenerate GRUB2 configuration file and reboot to test changes:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# reboot<br />
<br />
====Background image and bitmap fonts====<br />
<br />
GRUB2 comes with support for background images and bitmap fonts in {{ic|pf2}} format. The unifont font is included in the {{Pkg|grub-common}} package under the filename {{ic|unicode.pf2}}, or, as only ASCII characters under the name {{ic|ascii.pf2}}. <br />
<br />
Image formats supported include tga, png and jpeg, providing the correct modules are loaded. The maximum supported resolution depends on your hardware.<br />
<br />
Make sure you have set up the proper [https://wiki.archlinux.org/index.php/GRUB2#Setting_the_framebuffer_resolution framebuffer resolution].<br />
<br />
Edit {{ic|/etc/default/grub}} like this:<br />
GRUB_BACKGROUND="/boot/grub/myimage"<br />
#GRUB_THEME="/path/to/gfxtheme"<br />
<br />
{{Note|If you have installed GRUB on a separate partition, {{ic|/boot/grub/myimage}} becomes {{ic|/grub/myimage}}.}}<br />
<br />
To generate the changes and add the information into {{ic|grub.cfg}}, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If adding the splash image was successful, the user will see {{ic|"Found background image..."}} in the terminal as the command is executed. <br />
If this phrase is not seen, the image information was probably not incorporated into the {{ic|grub.cfg}} file.<br />
<br />
If the image is not displayed, check:<br />
* The path and the filename in {{ic|/etc/default/grub}} are correct.<br />
* The image is of the proper size and format (tga, png, 8-bit jpg).<br />
* The image was saved in the RGB mode, and is not indexed.<br />
* The console mode is not enabled in {{ic|/etc/default/grub}}.<br />
* The command {{ic|grub-mkconfig}} must be executed to place the background image information into the {{ic|/boot/grub/grub.cfg}} file.<br />
<br />
====Theme====<br />
<br />
Here is an example for configuring Starfield theme which was included in GRUB2 package.<br />
<br />
Edit {{ic|/etc/default/grub}}<br />
GRUB_THEME="/boot/grub/themes/starfield/theme.txt"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If configuring the theme was successful, you'll see {{ic|Found theme: /boot/grub/themes/starfield/theme.txt}} in the terminal.<br />
Your splash image will usually not displayed when using a theme.<br />
<br />
====Menu colors====<br />
<br />
As in GRUB Legacy (0.9x), you can change the menu colors in GRUB2. The available colors for GRUB2 are at https://www.gnu.org/software/grub/manual/html_node/Theme-file-format.html#Theme-file-format.<br />
Here is an example:<br />
<br />
Edit {{ic|/etc/default/grub}}:<br />
GRUB_COLOR_NORMAL="light-blue/black"<br />
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Hidden menu====<br />
<br />
One of the unique features of GRUB2 is hiding/skipping the menu and showing it by holding {{keypress|Esc}} when needed. You can also adjust whether you want to see the timeout counter.<br />
<br />
Edit {{ic|/etc/default/grub}} as you wish. Here is an example where the comments from the beginning of the two lines have been removed to enable the feature, the timeout has been set to five seconds and to be shown to the user:<br />
GRUB_HIDDEN_TIMEOUT=5<br />
GRUB_HIDDEN_TIMEOUT_QUIET=false<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Disable framebuffer====<br />
<br />
Users who use NVIDIA proprietary driver might wish to disable GRUB2's framebuffer as it can cause problems with the binary driver.<br />
<br />
To disable framebuffer, edit {{ic|/etc/default/grub}} and uncomment the following line:<br />
GRUB_TERMINAL_OUTPUT=console<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Other Options ===<br />
<br />
==== LVM ====<br />
<br />
If you use [[LVM]] for your {{ic|/boot}}, add the following before menuentry lines:<br />
<br />
insmod lvm<br />
<br />
and specify your root in the menuentry as:<br />
<br />
set root=(''lvm_group_name''-''lvm_logical_boot_partition_name'')<br />
<br />
Example:<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
insmod lvm<br />
set root=(VolumeGroup-lv_boot)<br />
# you can only set following two lines<br />
linux /vmlinuz-linux root=/dev/mapper/VolumeGroup-root ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
==== RAID ====<br />
<br />
GRUB2 provides convenient handling of RAID volumes. You need to add {{ic|insmod raid}} which allows you to address the volume natively. For example, {{ic|/dev/md0}} becomes:<br />
set root=(md0)<br />
<br />
whereas a partitioned RAID volume (e.g. {{ic|/dev/md0p1}}) becomes:<br />
set root=(md0,1)<br />
<br />
==== Persistent block device naming ====<br />
You can use UUIDs to detect partitions instead of the "old" {{ic|/dev/sd*}} and {{ic|/dev/hd*}} scheming. It has the advantage of detecting partitions by their unique UUIDs, which is needed by some people booting with complicated partition setups.<br />
<br />
UUIDs are used by default in the recent versions of GRUB2 - there is no downside in it anyway except that you need to re-generate the {{ic|grub.cfg}} file every time you resize or reformat your partitions. Remember this when modifying partitions with Live-CD.<br />
<br />
The recent versions of GRUB2 use UUIDs by default. You can re-enable the use of UUIDS by simply commenting the UUID line (this is also what it looks like by default):<br />
#GRUB_DISABLE_LINUX_UUID=true<br />
you can also just set the value as {{ic|false}} as shown here:<br />
GRUB_DISABLE_LINUX_UUID=false<br />
<br />
Either way, do not forget to generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Using Labels ====<br />
<br />
It is possible to use labels, human-readable strings attached to filesystems, by using the {{ic|--label}} option to {{ic|search}}. First of all, label your existing partition:<br />
# tune2fs -L a <LABEL> <PARTITION><br />
<br />
Then, add an entry using labels. An example of this:<br />
<br />
menuentry "Arch Linux, session texte" {<br />
search --label --no-floppy --set=root archroot<br />
linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro<br />
initrd /boot/initramfs-linux.img<br />
}<br />
<br />
==== Recall previous entry ====<br />
<br />
GRUB2 can remember the last entry you booted from and use this as the default entry to boot from next time. This is useful if you have multiple kernels (i.e., the current Arch one and the LTS kernel as a fallback option) or operating systems. To do this, edit {{ic|/etc/default/grub}} and change the setting of {{ic|GRUB_DEFAULT}}:<br />
<br />
GRUB_DEFAULT=saved<br />
<br />
This ensures that GRUB will default to the saved entry. To enable saving the selected entry, add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_SAVEDEFAULT=true<br />
<br />
{{Note|Manually added menu items, eg Windows in {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} , will need {{ic|savedefault}} added. Remember to regenerate your configuration file.}}<br />
<br />
==== Security ====<br />
<br />
If you want to secure GRUB2 so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB2's configuration files. To do this, run the command {{ic|grub-mkpasswd_pbkdf2}}. Enter a password and confirm it. The output will look like this:<br />
<br />
{{bc|<nowiki><br />
Your PBKDF2 is grub.pbkdf2.sha512.10000.C8ABD3E93C4DFC83138B0C7A3D719BC650E6234310DA069E6FDB0DD4156313DA3D0D9BFFC2846C21D5A2DDA515114CF6378F8A064C94198D0618E70D23717E82.509BFA8A4217EAD0B33C87432524C0B6B64B34FBAD22D3E6E6874D9B101996C5F98AB1746FE7C7199147ECF4ABD8661C222EEEDB7D14A843261FFF2C07B1269A</nowiki>}}Then, add the following to {{ic|/etc/grub.d/00_header}}:<br />
{{bc|<nowiki>cat << EOF<br />
<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
EOF</nowiki>}}<br />
where {{ic|<password>}} is the string generated by {{ic|grub-mkpasswd_pbkdf2}}.<br />
<br />
Regenerate your configuration file. Your GRUB2 command line, boot parameters and all boot entries are now protected.<br />
<br />
This can be relaxed and further customized with more users as described in the "Security" part of [https://www.gnu.org/software/grub/manual/grub.html#Security the GRUB manual].<br />
<br />
==== Root Encryption ====<br />
<br />
To let GRUB2 automatically add the kernel parameters for root encryption,<br />
add {{ic|1=cryptdevice=/dev/yourdevice:label}} to {{ic|GRUB_CMDLINE_LINUX}} in {{ic|/etc/defaults/grub}}.<br />
<br />
Example with root mapped to {{ic|/dev/mapper/root}}:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:root"<br />
<br />
Also, disable the usage of UUIDs for the rootfs:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
Regenerate the configuration.<br />
<br />
=== Booting an ISO Directly From GRUB2 ===<br />
Edit {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} to add an entry for the target ISO. When finished, update the GRUB menu as with the usual {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} (as root).<br />
<br />
==== Arch ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk/partition number of the isofile. Also adjust the {{ic|img_dev}} line to match this same location. However, if booting the ISO from USB on a computer which also has one internal HDD, then it needs to be {{ic|hd0,Y}} with {{ic|sdbY}}, instead of {{ic|sdaY}}.}}<br />
<br />
menuentry "Archlinux-2011.08.19-netinstall-x86_64.iso" {<br />
set isofile="/archives/archlinux-2011.08.19-netinstall-x86_64.iso"<br />
loopback loop (hd0,7)$isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=ARCH_201108 img_dev=/dev/sda7 img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
<br />
==== Ubuntu ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk or partition number of the ISO file.}}<br />
<br />
menuentry "ubuntu-12.04-desktop-amd64.iso" {<br />
set isofile="/path/to/ubuntu-12.04-desktop-amd64.iso"<br />
loopback loop (hdX,Y)$isofile<br />
linux (loop)/casper/vmlinuz boot=casper iso-scan/filename=$isofile quiet noeject noprompt splash --<br />
initrd (loop)/casper/initrd.lz<br />
}<br />
<br />
== Using the command shell ==<br />
<br />
Since the MBR is too small to store all GRUB2 modules, only the menu and a few basic commands reside there. The majority of GRUB2 functionality remains in modules in {{ic|/boot/grub}}, which are inserted as needed. In error conditions (e.g. if the partition layout changes) GRUB2 may fail to boot. When this happens, a command shell may appear.<br />
<br />
GRUB2 offers multiple shells/prompts. If there is a problem reading the menu but the bootloader is able to find the disk, you will likely be dropped to the "normal" shell:<br />
sh:grub><br />
<br />
If there is a more serious problem (e.g. GRUB cannot find required files), you may instead be dropped to the "rescue" shell:<br />
grub rescue><br />
<br />
The rescue shell is a restricted subset of the normal shell, offering much less functionality. If dumped to the rescue shell, first try inserting the "normal" module, then starting the "normal" shell:<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
grub rescue> insmod (hdX,Y)/boot/grub/i386-pc/normal.mod<br />
rescue:grub> normal<br />
<br />
=== Pager support ===<br />
<br />
GRUB2 supports pager for reading commands that provide long output (like the help command). This works only in normal shell mode and not in rescue mode. To enable pager, in GRUB2 command shell type:<br />
sh:grub> set pager=1<br />
<br />
== GUI configuration tools ==<br />
<br />
Following package may be installed from [[AUR]]<br />
* [https://aur.archlinux.org/packages.php?ID=44020 grub-customizer] (requires gettext gksu gtkmm hicolor-icon-theme openssl)<br />
*:Customize the bootloader (GRUB2 or BURG)<br />
* [http://kde-apps.org/content/show.php?content=139643 grub2-editor] (requires kdelibs)<br />
*:A KDE4 control module for configuring the GRUB2 bootloader<br />
* [http://kde-apps.org/content/show.php?content=137886 kcm-grub2] (requires kdelibs python2-qt kdebindings-python)<br />
*:This Kcm module manages the most common settings of Grub2.<br />
* [http://sourceforge.net/projects/startup-manager/ startupmanager] (requires gnome-python imagemagick yelp python2 xorg-xrandr)<br />
*:GUI app for changing the settings of GRUB, GRUB2, Usplash and Splashy<br />
<br />
== parttool or legacy hide/unhide ==<br />
<br />
If you have a Windows 9x paradigm with hidden C:\ disks GRUB Legacy had the hide/unhide feature. In GRUB2 this has been replaced by {{ic|parttool}}. For example, to boot the third C:\ disk of three Windows 9x installations on the CLI enter the CLI and:<br />
parttool hd0,1 hidden+ boot-<br />
parttool hd0,2 hidden+ boot-<br />
parttool hd0,3 hidden- boot+<br />
set root=hd0,3<br />
chainloader +1<br />
boot<br />
<br />
== Using the rescue console ==<br />
<br />
See [[#Using the command shell]] first. If unable to activate the standard shell, one possible solution is to boot using a live CD or some other rescue disk to correct configuration errors and reinstall GRUB. However, such a boot disk is not always available (nor necessary); the rescue console is surprisingly robust.<br />
<br />
The available commands in GRUB rescue include {{ic|insmod}}, {{ic|ls}}, {{ic|set}}, and {{ic|unset}}. This example uses {{ic|set}} and {{ic|insmod}}. {{ic|set}} modifies variables and {{ic|insmod}} inserts new modules to add functionality.<br />
<br />
Before starting, the user must know the location of their {{ic|/boot}} partition (be it a separate partition, or a subdirectory under their root):<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
<br />
where X is the physical drive number and Y is the partition number.<br />
<br />
To expand console capabilities, insert the {{ic|linux}} module:<br />
grub rescue> insmod (hdX,Y)/boot/grub/linux.mod<br />
<br />
{{Note|With a separate boot partition, omit {{ic|/boot}} from the path, (i.e. type {{ic|1=set prefix=(hdX,Y)/grub}} and {{ic|insmod (hdX,Y)/grub/linux.mod}}).}}<br />
<br />
This introduces the {{ic|linux}} and {{ic|initrd}} commands, which should be familiar (see [[#Configuration]]).<br />
<br />
An example, booting Arch Linux:<br />
set root=(hd0,5)<br />
linux /boot/vmlinuz-linux root=/dev/sda5<br />
initrd /boot/initramfs-linux.img<br />
boot<br />
<br />
With a separate boot partition, again change the lines accordingly:<br />
set root=(hd0,5)<br />
linux /vmlinuz-linux root=/dev/sda6<br />
initrd /initramfs-linux.img<br />
boot<br />
<br />
After successfully booting the Arch Linux installation, users can correct {{ic|grub.cfg}} as needed and then reinstall GRUB2.<br />
<br />
to reinstall GRUB2 and fix the problem completely, changing {{ic|/dev/sda}} if needed. See [[#Bootloader installation]] for details.<br />
<br />
== Combining the use of UUIDs and basic scripting ==<br />
<br />
If you like the idea of using UUIDs to avoid unreliable BIOS mappings or are struggling with GRUB's syntax, here is an example boot menu item that uses UUIDs and a small script to direct GRUB to the proper disk partitions for your system. All you need to do is replace the UUIDs in the sample with the correct UUIDs for your system. The example applies to a system with a boot and root partition. You will obviously need to modify the GRUB configuration if you have additional partitions:<br />
<br />
menuentry "Arch Linux 64" {<br />
# Set the UUIDs for your boot and root partition respectively<br />
set the_boot_uuid=ece0448f-bb08-486d-9864-ac3271bd8d07<br />
set the_root_uuid=c55da16f-e2af-4603-9e0b-03f5f565ec4a<br />
<br />
# (Note: This may be the same as your boot partition)<br />
<br />
# Get the boot/root devices and set them in the root and grub_boot variables<br />
search --fs-uuid --no-floppy --set=root $the_root_uuid<br />
search --fs-uuid --no-floppy --set=grub_boot $the_boot_uuid<br />
<br />
# Check to see if boot and root are equal.<br />
# If they are, then append /boot to $grub_boot (Since $grub_boot is actually the root partition)<br />
if [ $the_boot_uuid == $the_root_uuid] ; then<br />
set grub_boot=$grub_boot/boot<br />
fi<br />
<br />
# $grub_boot now points to the correct location, so the following will properly find the kernel and initrd<br />
linux ($grub_boot)/vmlinuz-linux root=/dev/disk/by-uuid/$uuid_os_root ro<br />
initrd ($grub_boot)/initramfs-linux.img<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
Any troubleshooting should be added here.<br />
<br />
=== Enable GRUB2 debug messages ===<br />
<br />
Add:<br />
<br />
set pager=1<br />
set debug=all<br />
<br />
to {{ic|grub.cfg}}.<br />
<br />
=== Correct GRUB2 No Suitable Mode Found Error ===<br />
<br />
If you get this error when booting any menuentry:<br />
<br />
error: no suitable mode found<br />
Booting however<br />
<br />
Then you need to initialize GRUB2 graphical terminal ({{ic|gfxterm}}) with proper video mode ({{ic|gfxmode}}) in GRUB2. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload'. In case of UEFI systems, if the GRUB2 video mode is not initialized, no kernel boot messages will be shown in the terminal (atleast until KMS kicks in).<br />
<br />
Copy {{ic|/usr/share/grub/unicode.pf2}} to ${GRUB2_PREFIX_DIR} ({{ic|/boot/grub/}} in case of BIOS and UEFI systems). If GRUB2 UEFI was installed with {{ic|1=--boot-directory=/boot/efi/EFI}} set, then the directory is {{ic|/boot/efi/EFI/grub/}}:<br />
<br />
# cp /usr/share/grub/unicode.pf2 ${GRUB2_PREFIX_DIR}<br />
<br />
If {{ic|/usr/share/grub/unicode.pf2}} does not exist, install {{Pkg|bdf-unifont}}, create the {{ic|unifont.pf2}} file and then copy it to {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}:<br />
<br />
# grub-mkfont -o unicode.pf2 /usr/share/fonts/misc/unifont.bdf<br />
<br />
Then, in the {{ic|grub.cfg}} file, add the following lines to enable GRUB2 to pass the video mode correctly to the kernel, without of which you will only get a black screen (no output) but booting (actually) proceeds successfully without any system hang.<br />
<br />
BIOS systems:<br />
<br />
insmod vbe<br />
<br />
UEFI systems:<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
<br />
After that add the following code (common to both BIOS and UEFI):<br />
<br />
insmod font<br />
<br />
if loadfont ${prefix}/fonts/unicode.pf2<br />
then<br />
insmod gfxterm<br />
set gfxmode=auto<br />
set gfxpayload=keep<br />
terminal_output gfxterm<br />
fi<br />
<br />
As you can see for gfxterm (graphical terminal) to function properly, {{ic|unicode.pf2}} font file should exist in {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}.<br />
<br />
=== msdos-style error message ===<br />
<br />
grub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding won't be possible!<br />
grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.<br />
However, blocklists are UNRELIABLE and its use is discouraged.<br />
grub-setup: error: If you really want blocklists, use --force.<br />
<br />
This error may occur when you try installing GRUB2 in a VMware container. Read more about it [https://bbs.archlinux.org/viewtopic.php?pid=581760#p581760 here]. It happens when the first partition starts just after the MBR (block 63), without the usual space of 1 MiB (2048 blocks) before the first partition. Read [[#MBR_aka_msdos_partitioning_specific_instructions]]<br />
<br />
=== UEFI GRUB2 drops to shell ===<br />
<br />
If GRUB loads but drops you into the rescue shell with no errors, it may be because of a missing or misplaced {{ic|grub.cfg}}. This will happen if GRUB2 UEFI was installed with {{ic|--boot-directory}} and {{ic|grub.cfg}} is missing OR if the partition number of the boot partition changed (which is hard-coded into the {{ic|grubx64.efi}} file).<br />
<br />
=== UEFI GRUB2 not loaded ===<br />
In some cases the EFI may fail to load GRUB correctly. Provided everything is set up correctly, the output of:<br />
efibootmgr -v<br />
might look something like this:<br />
BootCurrent: 0000<br />
Timeout: 3 seconds<br />
BootOrder: 0000,0001,0002<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\efi\grub\grub.efi)<br />
Boot0001* Shell HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\EfiShell.efi)<br />
Boot0002* Festplatte BIOS(2,0,00)P0: SAMSUNG HD204UI<br />
If everything works correctly, the EFI would now automatically load GRUB.<br />
<br />
If the screen only goes black for a second and the next boot option is tried afterwards, according to [https://bbs.archlinux.org/viewtopic.php?pid=981560#p981560 this post], moving GRUB to the partition root can help. The boot option has to be deleted and recreated afterwards. The entry for GRUB should look like this then:<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\grub.efi)<br />
<br />
=== Invalid signature ===<br />
If trying to boot Windows results in an "invalid signature" error, e.g. after reconfiguring partitions or adding additional hard drives, (re)move GRUB's device configuration and let it reconfigure:<br />
# mv /boot/grub/device.map /boot/grub/device.map-old<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
{{ic|grub-mkconfig}} should now mention all found boot options, including Windows. If it works, remove {{ic|/boot/grub/device.map-old}}.<br />
<br />
=== Restore GRUB Legacy ===<br />
<br />
* Move GRUB2 files out of the way:<br />
<br />
# mv /boot/grub /boot/grub.nonfunctional<br />
<br />
* Copy GRUB Legacy back to {{ic|/boot}}:<br />
<br />
# cp -af /boot/grub-legacy /boot/grub<br />
<br />
* Replace MBR and next 62 sectors of sda with backed up copy<br />
<br />
{{Warning|This command also restores the partition table, so be careful of overwriting a modified partition table with the old one. It '''will''' mess up your system.}}<br />
<br />
# dd if=/path/to/backup/first-sectors of=/dev/sdX bs=512 count=1<br />
<br />
A safer way is to restore only the MBR boot code use:<br />
<br />
# dd if=/path/to/backup/mbr-boot-code of=/dev/sdX bs=446 count=1<br />
<br />
== References ==<br />
<br />
# Official GRUB2 Manual - https://www.gnu.org/software/grub/manual/grub.html<br />
# Ubuntu wiki page for GRUB2 - https://help.ubuntu.com/community/Grub2<br />
# GRUB2 wiki page describing steps to compile for UEFI systems - https://help.ubuntu.com/community/UEFIBooting<br />
# Wikipedia's page on [[Wikipedia:BIOS Boot partition|BIOS Boot partition]]<br />
<br />
== External Links ==<br />
<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_bios.sh A Linux Bash Shell script to compile and install GRUB(2) for BIOS from BZR Source]<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_uefi.sh A Linux Bash Shell script to compile and install GRUB(2) for UEFI from BZR Source]</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=GRUB&diff=214410GRUB2012-07-24T06:47:01Z<p>Lfxgroove: /* Boot Microsoft Windows installed in BIOS-MBR mode */ Added a notice about which partition it is that you should find the bootmgr in since i thought it was on my win7 partition where i found a bootmgr in /windows/PCAT/bootmgr.</p>
<hr />
<div>[[Category:Boot loaders]]<br />
[[cs:GRUB2]]<br />
[[es:GRUB2]]<br />
[[fr:GRUB2]]<br />
[[id:GRUB2]]<br />
[[it:GRUB2]]<br />
[[ru:GRUB2]]<br />
[[tr:GRUB2]]<br />
[[zh-CN:GRUB2]]<br />
[[zh-TW:GRUB2]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers various aspects of the next generation of the GRand Unified Bootloader (GRUB2).}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Boot process overview}}}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Burg}} - Burg is a brand-new boot loader based on GRUB2. It uses a new object format which allows it to be built in a wider range of OS, including Linux, Windows, OS X, Solaris, FreeBSD, etc. It also has a highly configurable menu system which works in both text and graphic mode. <br />
{{Article summary heading|Resources}}<br />
{{Article summary link|GNU GRUB -- GNU Project|https://www.gnu.org/software/grub/}}<br />
{{Article summary end}}<br />
<br />
[https://www.gnu.org/software/grub/ GRUB2] is the next generation of the GRand Unified Bootloader (GRUB). GRUB2 is derived from [http://www.nongnu.org/pupa/ PUPA] which was a research project to investigate the next generation of GRUB. GRUB2 has been rewritten from scratch to clean up everything and provide modularity and portability [https://www.gnu.org/software/grub/grub-faq.en.html#q1].<br />
<br />
In brief, the ''bootloader'' is the first software program that runs when a computer starts. It is responsible for loading and transferring control to the Linux kernel. The kernel, in turn, initializes the rest of the operating system.<br />
<br />
== Preface ==<br />
Here is some information needs to be clarified:<br />
* The name ''GRUB'' officially refers to version ''2'' of the software, see [https://www.gnu.org/software/grub/]. If you are looking for the article on the legacy version, see [[GRUB Legacy]].<br />
<br />
* [[GRUB Legacy]] (i.e. version 0.9x) is considered legacy by upstream and is being replaced by GRUB2 and [[Syslinux]] in Arch Linux. See the news [https://www.archlinux.org/news/grub-legacy-no-longer-supported/ here]. Upstream recommends GRUB2 >=1.99 over GRUB Legacy, even for current GRUB Legacy users.<br />
<br />
* The [[Archboot]] ISO's installer script supports {{Pkg|grub-bios}} and {{Pkg|grub-efi-x86_64}} installation. The official installer script AIF (Arch Installation Framework) does not support GRUB(2) yet.<br />
<br />
* From 1.99-6 onwards, GRUB2 supports [[Btrfs]] as root (without a separate {{ic|/boot}} filesystem) compressed with either zlib or LZO.<br />
<br />
* For GRUB2 UEFI info, it is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this page.<br />
<br />
=== Notes for current GRUB Legacy users ===<br />
* Although GRUB legacy will not be removed from your system and will stay fully functional, you should consider upgrading to GRUB version 2.x, or one of the other supported bootloaders.<br />
<br />
* Upgrade from [[GRUB Legacy]] to [[GRUB]](2) is the much same as installing GRUB from a running Arch Linux which is covered [[#From a running Arch Linux|below]].<br />
<br />
* There are differences in the commands of GRUB and GRUB2. Familiarize yourself with [https://www.gnu.org/software/grub/manual/grub.html#Commands GRUB2 commands] before proceeding (e.g. "find" has been replaced with "search").<br />
<br />
* GRUB2 is now ''modular'' and no longer requires "stage 1.5". As a result, the bootloader itself is limited -- modules are loaded from the hard drive as needed to expand functionality (e.g. for [[LVM]] or RAID support).<br />
<br />
* Device naming has changed between GRUB and GRUB2. Partitions are numbered from 1 instead of 0 while drives are still numbered from 0, and prefixed with partition-table type. For example, {{ic|/dev/sda1}} would be referred to as {{ic|(hd0,msdos1)}} (for MBR) or {{ic|(hd0,gpt1)}} (for GPT) using GRUB2.<br />
<br />
=== Preliminary Requirements for GRUB2 ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== [[GPT]] specific instructions =====<br />
<br />
GRUB2 in BIOS-GPT configuration requires a BIOS Boot Partition to embed its {{ic|core.img}} in the absence of post-MBR gap in GPT partitioned systems (which is taken over by the GPT Primary Header and Primary Partition table). This partition is used by GRUB2 only in BIOS-GPT setups. No such partition type exists in case of MBR partitioning (at least not for GRUB2). This partition is also not required if the system is UEFI based, as no embedding of bootsectors takes place in that case. Syslinux does not require this partition.<br />
<br />
For a BIOS-GPT configuration, create a 2 MiB partition using cgdisk or GNU Parted with no filesystem. The location of the partition in the partition table does not matter but it should be within the first 2 TiB region of the disk. It is advisable to put it somewhere in the beginning of the disk before the {{ic|/boot}} partition. Set the partition type to "EF02" in cgdisk or {{ic|set <BOOT_PART_NUM> bios_grub on}} in GNU Parted.<br />
<br />
{{Note|This partition should be created before {{ic|grub-install}} or {{ic|grub-setup}} is run or before the '''Install Bootloader''' step of the Archlinux installer (if GRUB2 BIOS is selected as bootloader).}}<br />
<br />
===== [[MBR]] aka msdos partitioning specific instructions =====<br />
<br />
Usually the post-MBR gap (after the 512 byte MBR region and before the start of the 1st partition) in many MBR (or msdos disklabel) partitioned systems is 32 KiB when DOS compatibility cylinder alignment issues are satisfied in the partition table. However a post-MBR gap of about 1 to 2 MiB is recommended to provide sufficient room for embedding GRUB2's {{ic|core.img}} ({{bug|24103}}). It is advisable to use a partitioner which supports 1 MiB partition alignment to obtain this space as well as satisfy other non-512 byte sector issues (which are unrelated to embedding of {{ic|core.img}}).<br />
<br />
If you do not dual-boot with MS Windows (any version) in BIOS systems, it is advisable to switch to GPT partitioning - [[GUID_Partition_Table#Convert_from_MBR_to_GPT]]<br />
<br />
{{Note|Create the 2MiB partition mentioned above BEFORE you convert to GPT. If you do not, gparted will not resize your boot partition to allow its creation, and when you reboot GRUB2 will not know where to look.}}<br />
<br />
==== UEFI systems ====<br />
<br />
===== Create and Mount the UEFI SYSTEM PARTITION =====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
Follow [[Unified_Extensible_Firmware_Interface#Create_an_UEFI_System_Partition_in_Linux]] for instructions on creating a UEFI SYSTEM PARTITION. Then mount the UEFI SYSTEM PARTITION at {{ic|/boot/efi}}. If you have mounted the UEFISYS partition in some other mountpoint, replace {{ic|/boot/efi}} in the below instructions with that mountpoint:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat <UEFISYS_PART_DEVICE> /boot/efi<br />
<br />
Create a <UEFI_SYSTEM_PARTITION>{{ic|/EFI}} directory, if it does not exist:<br />
<br />
# mkdir -p /boot/efi/EFI<br />
<br />
== Installation ==<br />
<br />
=== During Arch Linux installation ===<br />
<br />
* Skip the '''Install Bootloader''' step and exit the installer.<br />
* Configure the network:<br />
# aif -p partial-configure-network<br />
This will bring up a prompt; put in the network interface to use, (e.g., {{ic|eth0}}) and use DHCP for easy configuration.<br />
* If you did not configure the installed system's {{ic|/etc/resolv.conf}} file during installation (for instance, if you plan to let DHCP generate it later), you will need to copy the one generated by AIF when it configured the network:<br />
# cp /etc/resolv.conf /mnt/etc/resolv.conf<br />
* If you run into network issues in the pacman update step below, you may have needed to install the {{Pkg|net-tools}} package.<br />
* Check and see if the {{ic|dm_mod}} module is loaded. If it is not, load it manually:<br />
# lsmod | grep dm_mod<br />
# modprobe dm-mod<br />
{{Note|This is necessary at this point, and cannot be postponed after the chroot. If you try to use modprobe in a chroot environment that has a later kernel version from that of the installing device (at the time of writing, 2.6.33), modprobe will fail. This happens routinely using the Arch "net" installations.}}<br />
* From the installer's live shell, chroot to the installed system:<br />
# mount -o bind /dev /mnt/dev<br />
# mount -t proc /proc /mnt/proc/<br />
# mount -t sysfs /sys /mnt/sys/<br />
# chroot /mnt bash<br />
* Refresh the package list (with an extra {{ic|-y}} flag to force a refresh of all package lists even if they appear to be up to date):<br />
# pacman -Syy<br />
* Install the GRUB2 package as mentioned in the section [[#From a running Arch Linux]] (Note that the {{ic|dm-mod}} module has already been loaded, no need to do that again).<br />
<br />
=== From a running Arch Linux ===<br />
<br />
==== BIOS systems ====<br />
<br />
===== Backup Important Data =====<br />
<br />
Although a GRUB(2) installation should run smoothly, it is strongly recommended to keep the GRUB Legacy files before installing {{Pkg|grub-bios}}.<br />
<br />
# mv /boot/grub /boot/grub-legacy<br />
<br />
Backup the MBR which contains the boot code and partition table (Replace {{ic|/dev/sd'''X'''}} with your actual disk path)<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/mbr_backup bs=512 count=1<br />
<br />
Only 446 bytes of the MBR contain boot code, the next 64 contain the partition table. If you do not want to overwrite your partition table when restoring, it is strongly advised to backup only the MBR boot code:<br />
<br />
# dd if=/dev/sdX of=/path/to/backup/bootcode_backup bs=446 count=1<br />
<br />
If unable to install GRUB2 correctly, see [[GRUB2#Restore_GRUB_Legacy]].<br />
<br />
===== Install grub-bios package =====<br />
<br />
The GRUB(2) packages can be installed with pacman (and will replace {{Pkg|grub-legacy}} or {{Pkg|grub}}, if it is installed):<br />
<br />
# pacman -S grub-bios<br />
<br />
{{Note|Simply installing the package won't update the {{ic|/boot/grub/i386-pc/core.img}} file and the GRUB(2) modules in {{ic|/boot/grub/i386-pc}}. You need to update them manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm_mod<br />
<br />
===== Install grub-bios boot files =====<br />
<br />
There are 3 ways to install GRUB(2) boot files in BIOS booting:<br />
*[[#Install_to_440-byte_MBR_boot_code_region]] (recommended) , <br />
*[[#Install_to_Partition_or_Partitionless_Disk]] (not recommended),<br />
*[[#Generate_core.img_alone]] (safest method, but requires another BIOS bootloader like [[grub-legacy]] or [[syslinux]] to be installed to chainload {{ic|/boot/grub/i386-pc/core.img}}). <br />
<br />
====== Install to 440-byte MBR boot code region ======<br />
<br />
To setup {{ic|grub-bios}} in the 440-byte Master Boot Record boot code region, populate the {{ic|/boot/grub}} directory, generate the {{ic|/boot/grub/i386-pc/core.img}} file, and embed it in the 32 KiB (minimum size - varies depending on partition alignment) post-MBR gap (MBR disks) or in BIOS Boot Partition (GPT disks), run:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
where {{ic|/dev/sda}} is the destination of the installation (in this case the MBR of the first SATA disk). If you use [[LVM]] for your {{ic|/boot}}, you can install GRUB2 on multiple physical disks. <br />
<br />
The {{ic|--no-floppy}} tells {{ic|grub-bios}} utilities not to search for any floppy devices which reduces the overall execution time of {{ic|grub-install}} on many systems (it will also prevent the issue below from occurring). Otherwise you get an error that looks like this:<br />
<br />
grub-probe: error: Cannot get the real path of '/dev/fd0'<br />
Auto-detection of a filesystem module failed.<br />
Please specify the module with the option '--modules' explicitly.<br />
<br />
{{Note|{{ic|--no-floppy}} has been removed from {{ic|grub-install}} in 2.00~beta2 upstream release, and replaced with {{ic|--allow-floppy}}.}}<br />
<br />
{{Warning|Make sure to check the {{ic|/boot}} directory if you use the latter. Sometimes the {{ic| boot-directory}} parameter creates another {{ic|/boot}} folder inside of {{ic|/boot}}. A wrong install would look like: {{ic|/boot/boot/grub/}}.}}<br />
<br />
====== Install to Partition or Partitionless Disk ======<br />
<br />
{{Note|{{ic|grub-bios}} (any version - including upstream Bazaar repo) does not encourage installation to a partition boot sector or a partitionless disk like GRUB Legacy or syslinux does. This kind of setup is prone to breakage, especially during updates, and is not supported by Arch devs.}}<br />
<br />
To set up {{ic|grub-bios}} to a partition boot sector, to a partitionless disk (also called superfloppy) or to a floppy disk, run (using for example {{ic|/dev/sdaX}} as the {{ic|/boot}} partition):<br />
<br />
# chattr -i /boot/grub/i386-pc/core.img<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --boot-directory=/boot --recheck --force --debug /dev/sdaX<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
# chattr +i /boot/grub/i386-pc/core.img<br />
<br />
You need to use the {{ic|--force}} option to allow usage of blocklists and should not use {{ic|1=--grub-setup=/bin/true}} (which is similar to simply generating {{ic|core.img}}).<br />
<br />
{{ic|grub-install}} will give out warnings like which should give you the idea of what might go wrong with this approach:<br />
<br />
/sbin/grub-setup: warn: Attempting to install GRUB to a partitionless disk or to a partition. This is a BAD idea.<br />
/sbin/grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists. <br />
However, blocklists are UNRELIABLE and their use is discouraged.<br />
<br />
Without {{ic|--force}} you may get the below error and {{ic|grub-setup}} will not setup its boot code in the partition boot sector:<br />
<br />
/sbin/grub-setup: error: will not proceed with blocklists<br />
<br />
With {{ic|--force}} you should get:<br />
<br />
Installation finished. No error reported.<br />
<br />
The reason why {{ic|grub-setup}} does not by default allow this is because in case of partition or a partitionless disk is that {{ic|grub-bios}} relies on embedded blocklists in the partition bootsector to locate the {{ic|/boot/grub/i386-pc/core.img}} file and the prefix dir {{ic|/boot/grub}}. The sector locations of {{ic|core.img}} may change whenever the filesystem in the partition is being altered (files copied, deleted etc.). For more info see https://bugzilla.redhat.com/show_bug.cgi?id=728742 and https://bugzilla.redhat.com/show_bug.cgi?id=730915.<br />
<br />
The workaround for this is to set the immutable flag on {{ic|/boot/grub/i386-pc/core.img}} (using chattr command as mentioned above) so that the sector locations of the {{ic|core.img}} file in the disk is not altered. The immutable flag on {{ic|/boot/grub/i386-pc/core.img}} needs to be set only if {{ic|grub-bios}} is installed to a partition boot sector or a partitionless disk, not in case of installtion to MBR or simple generation of {{ic|core.img}} without embedding any bootsector (mentioned above).<br />
<br />
====== Generate core.img alone ======<br />
<br />
To populate the {{ic|/boot/grub}} directory and generate a {{ic|/boot/grub/i386-pc/core.img}} file '''without''' embedding any {{ic|grub-bios}} bootsector code in the MBR, post-MBR region, or the partition bootsector, add {{ic|1=--grub-setup=/bin/true}} to {{ic|grub-install}}:<br />
<br />
# grub-install --directory=/usr/lib/grub/i386-pc --target=i386-pc --grub-setup=/bin/true --boot-directory=/boot --recheck --debug /dev/sda<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
You can then chainload GRUB2's {{ic|core.img}} from GRUB Legacy or syslinux as a Linux kernel or a multiboot kernel.<br />
<br />
===== Generate GRUB2 BIOS Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|/boot/grub/grub.cfg}}, NOT {{ic|/boot/grub/i386-pc/grub.cfg}}.}}<br />
<br />
If grub2 complains about "no suitable mode found" while booting, go to [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
If {{ic|grub-mkconfig}} fails, convert your {{ic|/boot/grub/menu.lst}} file to {{ic|/boot/grub/grub.cfg}} using:<br />
<br />
# grub-menulst2cfg /boot/grub/menu.lst /boot/grub/grub.cfg<br />
<br />
For example:<br />
<br />
{{hc|/boot/grub/menu.lst|<nowiki><br />
default=0<br />
timeout=5<br />
<br />
title Arch Linux Stock Kernel<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux.img<br />
<br />
title Arch Linux Stock Kernel Fallback<br />
root (hd0,0)<br />
kernel /vmlinuz-linux root=/dev/sda2 ro<br />
initrd /initramfs-linux-fallback.img<br />
</nowiki>}}<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
set default='0'; if [ x"$default" = xsaved ]; then load_env; set default="$saved_entry"; fi<br />
set timeout=5<br />
<br />
menuentry 'Arch Linux Stock Kernel' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux.img' '/initramfs-linux.img'<br />
<br />
}<br />
<br />
menuentry 'Arch Linux Stock Kernel Fallback' {<br />
set root='(hd0,1)'; set legacy_hdbias='0'<br />
legacy_kernel '/vmlinuz-linux' '/vmlinuz-linux' 'root=/dev/sda2' 'ro'<br />
legacy_initrd '/initramfs-linux-fallback.img' '/initramfs-linux-fallback.img'<br />
}<br />
</nowiki>}}<br />
<br />
If you forgot to create a GRUB2 {{ic|/boot/grub/grub.cfg}} config file and simply rebooted into GRUB2 Command Shell, type:<br />
<br />
sh:grub> insmod legacycfg<br />
sh:grub> legacy_configfile ${prefix}/menu.lst<br />
<br />
Boot into Arch and re-create the proper GRUB2 {{ic|/boot/grub/grub.cfg}} config file.<br />
<br />
{{Note|This option works only in BIOS systems, not in UEFI systems.}}<br />
<br />
===== Multiboot in BIOS =====<br />
<br />
====== Boot Microsoft Windows installed in BIOS-MBR mode ======<br />
<br />
{{Note|GRUB2 supports booting {{ic|bootmgr}} directly and chainload of partition boot sector is no longer required to boot Windows in a BIOS-MBR setup.}}<br />
<br />
{{Note|Take note that it is the SYSTEM PARTITION that has the bootmgr, not your "real" windows partition, ie: when showing all UUID's with blkid it is the partition with LABEL&#61;"SYSTEM RESERVED" which is only about 100 mb big much like the boot partition for arch.}}<br />
<br />
Find the UUID of the NTFS filesystem of the Windows's SYSTEM PARTITION where the {{ic|bootmgr}} and its files reside. For example, if Windows {{ic|bootmgr}} exists at {{ic|/media/Windows/bootmgr}}:<br />
<br />
# grub-probe --target=fs_uuid /media/Windows/bootmgr<br />
69B235F6749E84CE<br />
<br />
Then, add the below code to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} and regenerate {{ic|grub.cfg}} with {{ic|grub-mkconfig}} as explained above to boot Windows (Vista, 7 or 8) installed in BIOS-MBR mode:<br />
<br />
<pre><br />
menuentry "Microsoft Windows 7 BIOS-MBR" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /bootmgr<br />
}</pre><br />
<br />
For Windows XP:<br />
<br />
menuentry "Microsoft Windows XP" {<br />
insmod part_msdos<br />
insmod ntfs<br />
insmod search_fs_uuid<br />
insmod ntldr <br />
search --fs-uuid --no-floppy --set=root 69B235F6749E84CE<br />
ntldr /ntldr<br />
}<br />
<br />
==== UEFI systems ====<br />
<br />
{{Note|It is recommended to read the [[UEFI]], [[GPT]] and [[UEFI_Bootloaders]] pages before reading this part.}}<br />
<br />
===== Install grub-uefi package =====<br />
<br />
{{Note|Unless specified as EFI 1.x , EFI and UEFI terms are used interchangeably to denote UEFI 2.x firmware. Also unless stated explicitely, the instructions are general and not Mac specific. Some of them may not work or may be different in Macs. Apple's EFI implementation is neither a EFI 1.x version nor UEFI 2.x version but mixes up both. This kind of firmware does not fall under any one UEFI Specification version and is therefore not a standard UEFI firmware.}}<br />
<br />
GRUB2 UEFI bootloader is available in Arch Linux only from version 1.99~rc1. To install, first [[Unified_Extensible_Firmware_Interface#Detecting_UEFI_Firmware_Arch|detect which UEFI firmware arch]] you have (either x86_64 or i386).<br />
<br />
Depending on that, install the appropriate package<br />
<br />
For 64-bit aka x86_64 UEFI firmware:<br />
# pacman -S grub-efi-x86_64<br />
<br />
For 32-bit aka i386 UEFI firmware:<br />
# pacman -S grub-efi-i386<br />
<br />
{{Note|Simply installing the package will not update the {{ic|grub.efi}} file and the GRUB(2) modules in the UEFI System Partition. You need to do this manually using {{ic|grub-install}} as explained below.}}<br />
<br />
Also load the device-mapper kernel module without which {{ic|grub-probe}} does not reliably detect disks and partitions:<br />
<br />
# modprobe dm-mod<br />
<br />
===== Install grub-uefi boot files =====<br />
<br />
====== Install to UEFI SYSTEM PARTITION ======<br />
<br />
{{Note|The below commands assume you are using {{ic|grub-efi-x86_64}} (for {{ic|grub-efi-i386}} replace {{ic|x86_64}} with {{ic|i386}} in the below commands).}}<br />
<br />
The UEFI system partition will need to be mounted at {{ic|/boot/efi/}} for the GRUB2 install script to detect it:<br />
<br />
# mkdir -p /boot/efi<br />
# mount -t vfat /dev/sdXY /boot/efi<br />
<br />
Install GRUB UEFI application to {{ic|/boot/efi/EFI/arch_grub}} and its modules to {{ic|/boot/grub/x86_64-efi}} (recommended) using:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot --recheck --debug<br />
# mkdir -p /boot/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/grub/locale/en.mo<br />
<br />
If you want to install grub2 modules and {{ic|grub.cfg}} at the directory {{ic|/boot/efi/EFI/grub}} and the {{ic|grubx64.efi}} application at {{ic|/boot/efi/EFI/arch_grub}} use:<br />
<br />
# grub-install --directory=/usr/lib/grub/x86_64-efi --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=arch_grub --boot-directory=/boot/efi/EFI --recheck --debug<br />
# mkdir -p /boot/efi/EFI/grub/locale<br />
# cp /usr/share/locale/en\@quot/LC_MESSAGES/grub.mo /boot/efi/EFI/grub/locale/en.mo<br />
<br />
In this case {{ic|grub-efi-x86_64}} will be installed into {{ic|/boot/grub}}, making the behavior consistent with the BIOS verion of GRUB2, but this is not recommended if you use both {{ic|grub-bios}} and {{ic|grub-efi-x86_64}} in your system, as this will overwrite {{ic|grub-bios }}modules in {{ic|/boot/grub}}.<br />
<br />
The {{ic|--efi-directory}} option mentions the mountpoint of UEFI SYSTEM PARTITION , {{ic|--bootloader-id}} mentions the name of the directory used to store the {{ic|grubx64.efi}} file and {{ic|--boot-directory}} mentions the directory wherein the actual modules will be installed (and into which {{ic|grub.cfg}} should be created).<br />
<br />
The actual paths are:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi<br />
<br />
<boot-directory>/grub/x86_64-efi/<all modules, grub.efi, core.efi, grub.cfg><br />
<br />
{{Note|the {{ic|--bootloader-id}} option does not change {{ic|<boot-directory>/grub}}, i.e. you cannot install the modules to {{ic|<boot-directory>/<bootloader-id>}}, the path is hard-coded to be {{ic|<boot-directory>/grub}}.}}<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == <boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot/efi/EFI --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/efi/EFI/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=arch_grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/arch_grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
In {{ic|<nowiki>--efi-directory=/boot/efi --boot-directory=/boot --bootloader-id=grub</nowiki>}}:<br />
<br />
<efi-directory>/<EFI or efi>/<bootloader-id> == /boot/efi/EFI/grub<br />
<boot-directory>/grub == /boot/grub<br />
<br />
The {{ic|<nowiki><efi-directory>/<EFI or efi>/<bootloader-id>/grubx64.efi</nowiki>}} is an exact copy of {{ic|<nowiki><boot-directory>/grub/x86_64-efi/core.efi</nowiki>}}.<br />
<br />
{{Note|In GRUB2 2.00~beta4, the {{ic|grub-install}} option {{ic|--efi-directory}} replaces {{ic|--root-directory}} and the latter is deprecated.}}<br />
{{Note|The options {{ic|--efi-directory}} and {{ic|--bootloader-id}} are specific to GRUB2 UEFI.}}<br />
<br />
In all the cases the UEFI SYSTEM PARTITION should be mounted for {{ic|grub-install}} to install {{ic|grubx64.efi}} in it, which will be launched by the firmware (using the {{ic|efibootmgr}} created boot entry in non-Mac systems).<br />
<br />
If you notice carefully, there is no <device_path> option (Eg: {{ic|/dev/sda}}) at the end of the {{ic|grub-install}} command unlike the case of setting up GRUB2 for BIOS systems. Any <device_path> provided will be ignored by the install script as UEFI bootloaders do not use MBR or Partition boot sectors at all.<br />
<br />
You may now be able to UEFI boot your system by creating a {{ic|grub.cfg}} file by following [[#Generate_GRUB2_UEFI_Config_file]] and [[#Create_GRUB2_entry_in_the_Firmware_Boot_Manager]].<br />
<br />
===== Create GRUB2 entry in the Firmware Boot Manager =====<br />
<br />
====== Non-Mac UEFI systems ======<br />
<br />
{{ic|grub-install}} will ensure that {{ic|/boot/efi/EFI/arch_grub/grubx64.efi}} is launched by default if it detects {{ic|efibootmgr}} and if it is able to access UEFI Runtime Services. Follow [[Unified_Extensible_Firmware_Interface#efibootmgr]] for more info.<br />
<br />
If you have problems running GRUB2 in UEFI mode you can try the following (worked on an ASUS Z68 mainboard):<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/shellx64.efi<br />
<br />
or<br />
<br />
# cp /boot/efi/EFI/arch_grub/grubx64.efi /boot/efi/EFI/tools/shellx64.efi<br />
<br />
After this launch the UEFI Shell from the UEFI setup/menu (in ASUS UEFI BIOS, switch to advanced mode, press Exit in the top right corner and choose "Launch EFI shell from filesystem device"). The GRUB2 menu will show up and you can boot into your system. Afterwards you can use efibootmgr to setup a menu entry (see above).<br />
<br />
====== Apple Mac EFI systems ======<br />
<br />
{{Note|TODO: GRUB upstream Bazaar mactel branch http://bzr.savannah.gnu.org/lh/grub/branches/mactel/changes. No further update from grub developers.}}<br />
{{Note|TODO: Experimental "bless" utility for Linux by Fedora developers - {{AUR|mactel-boot}}. Requires more testing.}}<br />
<br />
Use bless command from within Mac OS X to set {{ic|grubx64.efi}} as the default boot option. You can also boot from the Mac OS X install disc and launch a Terminal there if you only have Linux installed. In the Terminal, create a directory and mount the EFI System Partition:<br />
<br />
# cd /Volumes<br />
# mkdir efi<br />
# mount -t msdos /dev/disk0s1 /Volumes/efi<br />
<br />
Then run bless on {{ic|grub.efi}} and on the EFI partition to set them as the default boot options.<br />
<br />
# bless --folder=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
# bless --mount=/Volumes/efi --file=/Volumes/efi/efi/arch_grub/grubx64.efi --setBoot<br />
<br />
More info at https://help.ubuntu.com/community/UEFIBooting#Apple_Mac_EFI_systems_.28both_EFI_architecture.29.<br />
<br />
===== Generate GRUB2 UEFI Config file =====<br />
<br />
Finally, generate a configuration for GRUB2 (this is explained in greater detail in the Configuration section):<br />
<br />
# grub-mkconfig -o <boot-directory>/grub/grub.cfg<br />
<br />
{{Note|The file path is {{ic|<boot-directory>/grub/grub.cfg}}, NOT {{ic|<boot-directory>/grub/x86_64-efi/grub.cfg}}.}}<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If you used {{ic|<nowiki>--boot-directory=/boot/efi/EFI</nowiki>}}:<br />
<br />
# grub-mkconfig -o /boot/efi/EFI/grub/grub.cfg<br />
<br />
This is independent of the value of {{ic|--bootloader-id}} option.<br />
<br />
If GRUB2 complains about "no suitable mode found" while booting, try [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]].<br />
<br />
===== Create GRUB2 Standalone UEFI Application =====<br />
<br />
It is possible to create a {{ic|grubx64_standalone.efi}} application which has all the modules embeddded in a memdisk within the uefi application, thus removing the need for having a separate directory populated with all the GRUB2 uefi modules and other related files. This is done using the {{ic|grub-mkstandalone}} command which is included in {{Pkg|grub-common}} >= 1:1.99-6 package.<br />
<br />
The easiest way to do this would be with the install command already mentioned before, but specifying the modules to include. For example:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" <any extra files you want to include><br />
<br />
The {{ic|grubx64_standalone.efi}} file expects {{ic|grub.cfg}} to be within its $prefix which is {{ic|(memdisk)/boot/grub}}. The memdisk is embedded within the efi app. The {{ic|grub-mkstandlone}} script allow passing files to be included in the memdisk image to be as the arguments to the script (in <any extra files you want to include>).<br />
<br />
If you have the {{ic|grub.cfg}} at {{ic|/home/user/Desktop/grub.cfg}}, then create a temporary {{ic|/home/user/Desktop/boot/grub/}} directory, copy the {{ic|/home/user/Desktop/grub.cfg}} to {{ic|/home/user/Desktop/boot/grub/grub.cfg}}, cd into {{ic|/home/user/Desktop/boot/grub/}} and run:<br />
<br />
# grub-mkstandalone --directory="/usr/lib/grub/x86_64-efi/" --format="x86_64-efi" --compression="xz" \<br />
--output="/boot/efi/EFI/arch_grub/grubx64_standalone.efi" "boot/grub/grub.cfg"<br />
<br />
The reason to cd into {{ic|/home/user/Desktop/boot/grub/}} and to pass the file path as {{ic|boot/grub/grub.cfg}} (notice the lack of a leading slash - boot/ vs /boot/ ) is because {{ic|dir1/dir2/file}} is included as {{ic|(memdisk)/dir1/dir2/file}} by the {{ic|grub-mkstandalone}} script. <br />
<br />
If you pass {{ic|/home/user/Desktop/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/grub.cfg}}. If you pass {{ic|/home/user/Desktop/boot/grub/grub.cfg}} the file will be included as {{ic|(memdisk)/home/user/Desktop/boot/grub/grub.cfg}}. That is the reason for cd'ing into {{ic|/home/user/Desktop/boot/grub/}} and passing {{ic|boot/grub/grub.cfg}}, to include the file as {{ic|(memdisk)/boot/grub/grub.cfg}}, which is what {{ic|grub.efi}} expects the file to be.<br />
<br />
You need to create an UEFI Boot Manager entry for {{ic|/boot/efi/EFI/arch_grub/grubx64_standalone.efi}} using {{ic|efibootmgr}}. Follow [[#Create GRUB2 entry in the Firmware Boot Manager]].<br />
<br />
===== Multiboot in UEFI =====<br />
<br />
====== Chainload Microsoft Windows x86_64 UEFI-GPT ======<br />
<br />
Find the UUID of the FAT32 filesystem in the UEFI SYSTEM PARTITION where the Windows UEFI Bootloader files reside. For example, if Windows {{ic|bootmgfw.efi}} exists at {{ic|/boot/efi/EFI/Microsoft/Boot/bootmgfw.efi}} (ignore the upper-lower case differences since that is immaterial in FAT filesystem):<br />
<br />
# grub-probe --target=fs_uuid /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
1ce5-7f28<br />
<br />
# grub-probe --target=hints_string /boot/efi/EFI/Microsoft/Boot/bootmgfw.efi<br />
--hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1<br />
<br />
Then, add this code to {{ic|/boot/grub/grub.cfg}} OR {{ic|/boot/efi/EFI/grub/grub.cfg}} to chainload Windows x86_64 (Vista SP1+, 7 or 8) installed in UEFI-GPT mode:<br />
<br />
menuentry "Microsoft Windows x86_64 UEFI-GPT" {<br />
insmod part_gpt<br />
insmod fat<br />
insmod search_fs_uuid<br />
insmod chain<br />
search --fs-uuid --no-floppy --set=root --hint-bios=hd0,gpt1 --hint-efi=hd0,gpt1 --hint-baremetal=ahci0,gpt1 1ce5-7f28<br />
chainloader /efi/Microsoft/Boot/bootmgfw.efi<br />
}<br />
<br />
== Configuration ==<br />
<br />
You can also choose to automatically generate or manually edit {{ic|grub.cfg}}.<br />
<br />
{{Note|For EFI systems, if GRUB2 was installed with the {{ic|--boot-directory}} option set, the {{ic|grub.cfg}} file must be placed in the same directory as {{ic|grubx64.efi}}. Otherwise, the {{ic|grub.cfg}} file goes in {{ic|/boot/grub/}}, just like in the BIOS version of GRUB2.}}<br />
<br />
{{Note|Here is a quite complete description of how to configure GRUB2: http://members.iinet.net/~herman546/p20/GRUB2%20Configuration%20File%20Commands.html }}<br />
<br />
=== Automatically generating using grub-mkconfig (Recommended) ===<br />
<br />
The GRUB2 {{ic|menu.lst}} equivalent configuration files are {{ic|/etc/default/grub}} and {{ic|/etc/grub.d/*}}. {{ic|grub-mkconfig}} uses these files to generate {{ic|grub.cfg}}. By default the script outputs to stdout. To generate a {{ic|grub.cfg}} file run the command:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{ic|/etc/grub.d/10_linux}} is set to automatically add menu items for Arch linux that work out of the box, to any generated configuration. Other operating systems may need to be added manually to {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}}<br />
<br />
==== Additional arguments ====<br />
<br />
To pass custom additional arguments to the Linux image, you can set the {{ic|GRUB_CMDLINE_LINUX}} variable in {{ic|/etc/default/grub}}. This is analogous to adding commands to the kernel line in GRUB Legacy.<br />
<br />
For example, use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/sdaX"</nowiki>}} where {{ic|sda'''X'''}} is your swap partition to enable resume after hibernation.<br />
<br />
You can also use {{ic|<nowiki>GRUB_CMDLINE_LINUX="resume=/dev/disk/by-uuid/${swap_uuid}"</nowiki>}}, where {{ic|${swap_uuid} }} is the [[Persistent_block_device_naming|UUID]] of your swap partition.<br />
<br />
Users who have replaced the default SysV init with [[systemd]] will want to add {{ic|<nowiki>init=/bin/systemd</nowiki>}} to their {{ic|<nowiki>GRUB_CMDLINE_LINUX</nowiki>}}.<br />
<br />
=== Manually creating grub.cfg ===<br />
<br />
{{Warning|Editing this file is strongly ''not'' recommended. The file is generated by the {{ic|grub-mkconfig}} command, and it is best to edit your {{ic|/etc/default/grub}} or one of the scripts in the {{ic|/etc/grub.d}} folder.}}<br />
<br />
A basic GRUB config file uses the following options<br />
* {{ic|(hdX,Y)}} is the partition {{ic|Y}} on disk {{ic|X}}, partition numbers starting at 1, disk numbers starting at 0<br />
* {{ic|1=set default=N}} is the default boot entry that is chosen after timeout for user action<br />
* {{ic|1=set timeout=M}} is the time {{ic|M}} to wait in seconds for a user selection before default is booted<br />
* {{ic|<nowiki>menuentry "title" {entry options}</nowiki>}} is a boot entry titled {{ic|title}}<br />
* {{ic|1=set root=(hdX,Y)}} sets the boot partition, where the kernel and GRUB modules are stored (boot need not be a separate partition, and may simply be a directory under the "root" partition ({{ic|/}})<br />
<br />
An example configuration:<br />
<br />
{{hc<br />
|/boot/grub/grub.cfg<br />
|<nowiki><br />
# Config file for GRUB2 - The GNU GRand Unified Bootloader<br />
# /boot/grub/grub.cfg<br />
<br />
# DEVICE NAME CONVERSIONS<br />
#<br />
# Linux Grub<br />
# -------------------------<br />
# /dev/fd0 (fd0)<br />
# /dev/sda (hd0)<br />
# /dev/sdb2 (hd1,2)<br />
# /dev/sda3 (hd0,3)<br />
#<br />
<br />
# Timeout for menu<br />
set timeout=5<br />
<br />
# Set default boot entry as Entry 0<br />
set default=0<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
set root=(hd0,1)<br />
linux /vmlinuz-linux root=/dev/sda3 ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
## (1) Windows<br />
#menuentry "Windows" {<br />
#set root=(hd0,3)<br />
#chainloader +1<br />
#}<br />
</nowiki>}}<br />
<br />
=== Dual-booting ===<br />
<br />
{{Note|If you want GRUB2 to automatically search for other systems, you may wish to install {{Pkg|os-prober}}.}}<br />
<br />
==== Using grub-mkconfig ====<br />
The best way to add other entries is editing the {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} . The entries in this file will be automatically added when running {{ic|grub-mkconfig}}.<br />
After adding the new lines, run:<br />
# grub-mkconfig -o /boot/grub/grub.cfg <br />
to generate an updated {{ic|grub.cfg}}.<br />
<br />
===== With GNU/Linux =====<br />
<br />
Assuming that the other distro is on partition {{ic|sda2}}:<br />
<br />
menuentry "Other Linux" {<br />
set root=(hd0,2)<br />
linux /boot/vmlinuz (add other options here as required)<br />
initrd /boot/initrd.img (if the other kernel uses/needs one)<br />
}<br />
<br />
===== With FreeBSD =====<br />
<br />
Requires that FreeBSD is installed on a single partition with UFS. Assuming it is installed on {{ic|sda4}}:<br />
<br />
menuentry "FreeBSD" {<br />
set root=(hd0,4)<br />
chainloader +1<br />
}<br />
<br />
===== With Windows =====<br />
<br />
This assumes that your Windows partition is {{ic|sda3}}.<br />
<br />
# (2) Windows XP<br />
menuentry "Windows XP" {<br />
set root=(hd0,3)<br />
chainloader (hd0,3)+1<br />
}<br />
<br />
If the Windows bootloader is on an entirely different hard drive than GRUB, it may be necessary to trick Windows into believing that it is the first hard drive. This was possible in GRUB Legacy with {{ic|map}} and is now done with {{ic|drivemap}}. Assuming GRUB is on {{ic|hd0}} and Windows is on {{ic|hd2}}, you need to add the following after {{ic|set root}}:<br />
<br />
drivemap -s hd0 hd2<br />
<br />
==== With Windows via EasyBCD and NeoGRUB ====<br />
<br />
Since EasyBCD's NeoGRUB currently does not understand the GRUB2 menu format, chainload to it by replacing the contents of your {{ic|C:\NST\menu.lst}} file with lines similar to the following:<br />
<br />
default 0<br />
timeout 1<br />
<br />
title Chainload into GRUB v2<br />
root (hd0,7)<br />
kernel /boot/grub/i386-pc/core.img<br />
<br />
===Visual Configuration===<br />
<br />
In GRUB2 it is possible, by default, to change the look of the menu. Make sure to initialize, if not done already, GRUB2 graphical terminal, gfxterm, with proper video mode, gfxmode, in GRUB2. This can be seen in the section [[#Correct_GRUB2_No_Suitable_Mode_Found_Error]]. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload' so any visual configurations need this mode in order to be in effect.<br />
<br />
====Setting the framebuffer resolution ====<br />
<br />
GRUB2 can set the framebuffer for both GRUB2 itself and the kernel. The old {{ic|1=vga=}} way is deprecated. The preferred method is editing {{ic|/etc/default/grub}} as the following sample:<br />
<br />
GRUB_GFXMODE=1024x768x32<br />
GRUB_GFXPAYLOAD_LINUX=keep<br />
<br />
To generate the changes, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
The {{ic|gfxpayload}} property will make sure the kernel keeps the resolution.<br />
<br />
{{Note|If this example does not work for you try to replace {{ic|1=gfxmode="1024x768x32"}} by {{ic|1=vbemode="0x105"}}. Remember to replace the specified resolution with one suitable for your screen.}}<br />
{{Note|To show all the modes you can use {{ic|1=# hwinfo --framebuffer}} (hwinfo is available in [community]), while at GRUB2 prompt you can use the {{ic|1=vbeinfo}} command.}}<br />
<br />
If this method does not work for you, the deprecated {{ic|1=vga=}} method will still work. Just<br />
add it next to the {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="}} line in {{ic|/etc/default/grub}}<br />
for eg: {{ic|1="GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vga=792"}} will give you a {{ic|1024x768}} resolution.<br />
<br />
You can choose one of these resolutions: {{ic|640×480}}, {{ic|800×600}}, {{ic|1024×768}}, {{ic|1280×1024}}, {{ic|1600×1200}}<br />
<br />
====915resolution hack ====<br />
<br />
Some times for Intel graphic adapters neither {{ic|1=# hwinfo --framebuffer}} nor {{ic|1=vbeinfo}} will show you the desired resolution. In this case you can use {{ic|915resolution}} hack. This hack will temporarily modify video BIOS and add needed resolution. See [http://915resolution.mango-lang.org/ 915resolution's home page]<br />
<br />
In the following I will proceed with the example for my system. Please adjust the recipe for your needs. First you need to find a video mode which will be modified later. For that, run {{ic|915resolution}} in GRUB2 command shell:<br />
915resolution -l<br />
The output will be something like:<br />
Intel 800/900 Series VBIOS Hack : version 0.5.3<br />
...<br />
Mode 30 : 640x480, 8 bits/pixel<br />
...<br />
Next, our purpose is to overwrite mode 30. (You can choose what ever mode you want.) In the file {{ic|/etc/grub.d/00_header}} just before the {{ic|set gfxmode&#61;${GRUB_GFXMODE}}} line insert:<br />
915resolution 30 1440 900<br />
Here we are overwriting the mode {{ic|30}} with {{ic|1440x900}} resolution. Lastly we need to set {{ic|GRUB_GFXMODE}} as described earlier, regenerate GRUB2 configuration file and reboot to test changes:<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# reboot<br />
<br />
====Background image and bitmap fonts====<br />
<br />
GRUB2 comes with support for background images and bitmap fonts in {{ic|pf2}} format. The unifont font is included in the {{Pkg|grub-common}} package under the filename {{ic|unicode.pf2}}, or, as only ASCII characters under the name {{ic|ascii.pf2}}. <br />
<br />
Image formats supported include tga, png and jpeg, providing the correct modules are loaded. The maximum supported resolution depends on your hardware.<br />
<br />
Make sure you have set up the proper [https://wiki.archlinux.org/index.php/GRUB2#Setting_the_framebuffer_resolution framebuffer resolution].<br />
<br />
Edit {{ic|/etc/default/grub}} like this:<br />
GRUB_BACKGROUND="/boot/grub/myimage"<br />
#GRUB_THEME="/path/to/gfxtheme"<br />
<br />
{{Note|If you have installed GRUB on a separate partition, {{ic|/boot/grub/myimage}} becomes {{ic|/grub/myimage}}.}}<br />
<br />
To generate the changes and add the information into {{ic|grub.cfg}}, run: <br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If adding the splash image was successful, the user will see {{ic|"Found background image..."}} in the terminal as the command is executed. <br />
If this phrase is not seen, the image information was probably not incorporated into the {{ic|grub.cfg}} file.<br />
<br />
If the image is not displayed, check:<br />
* The path and the filename in {{ic|/etc/default/grub}} are correct.<br />
* The image is of the proper size and format (tga, png, 8-bit jpg).<br />
* The image was saved in the RGB mode, and is not indexed.<br />
* The console mode is not enabled in {{ic|/etc/default/grub}}.<br />
* The command {{ic|grub-mkconfig}} must be executed to place the background image information into the {{ic|/boot/grub/grub.cfg}} file.<br />
<br />
====Theme====<br />
<br />
Here is an example for configuring Starfield theme which was included in GRUB2 package.<br />
<br />
Edit {{ic|/etc/default/grub}}<br />
GRUB_THEME="/boot/grub/themes/starfield/theme.txt"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If configuring the theme was successful, you'll see {{ic|Found theme: /boot/grub/themes/starfield/theme.txt}} in the terminal.<br />
Your splash image will usually not displayed when using a theme.<br />
<br />
====Menu colors====<br />
<br />
As in GRUB Legacy (0.9x), you can change the menu colors in GRUB2. The available colors for GRUB2 are at https://www.gnu.org/software/grub/manual/html_node/Theme-file-format.html#Theme-file-format.<br />
Here is an example:<br />
<br />
Edit {{ic|/etc/default/grub}}:<br />
GRUB_COLOR_NORMAL="light-blue/black"<br />
GRUB_COLOR_HIGHLIGHT="light-cyan/blue"<br />
<br />
Generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Hidden menu====<br />
<br />
One of the unique features of GRUB2 is hiding/skipping the menu and showing it by holding {{keypress|Esc}} when needed. You can also adjust whether you want to see the timeout counter.<br />
<br />
Edit {{ic|/etc/default/grub}} as you wish. Here is an example where the comments from the beginning of the two lines have been removed to enable the feature, the timeout has been set to five seconds and to be shown to the user:<br />
GRUB_HIDDEN_TIMEOUT=5<br />
GRUB_HIDDEN_TIMEOUT_QUIET=false<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
====Disable framebuffer====<br />
<br />
Users who use NVIDIA proprietary driver might wish to disable GRUB2's framebuffer as it can cause problems with the binary driver.<br />
<br />
To disable framebuffer, edit {{ic|/etc/default/grub}} and uncomment the following line:<br />
GRUB_TERMINAL_OUTPUT=console<br />
<br />
and run:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Other Options ===<br />
<br />
==== LVM ====<br />
<br />
If you use [[LVM]] for your {{ic|/boot}}, add the following before menuentry lines:<br />
<br />
insmod lvm<br />
<br />
and specify your root in the menuentry as:<br />
<br />
set root=(''lvm_group_name''-''lvm_logical_boot_partition_name'')<br />
<br />
Example:<br />
<br />
# (0) Arch Linux<br />
menuentry "Arch Linux" {<br />
insmod lvm<br />
set root=(VolumeGroup-lv_boot)<br />
# you can only set following two lines<br />
linux /vmlinuz-linux root=/dev/mapper/VolumeGroup-root ro<br />
initrd /initramfs-linux.img<br />
}<br />
<br />
==== RAID ====<br />
<br />
GRUB2 provides convenient handling of RAID volumes. You need to add {{ic|insmod raid}} which allows you to address the volume natively. For example, {{ic|/dev/md0}} becomes:<br />
set root=(md0)<br />
<br />
whereas a partitioned RAID volume (e.g. {{ic|/dev/md0p1}}) becomes:<br />
set root=(md0,1)<br />
<br />
==== Persistent block device naming ====<br />
You can use UUIDs to detect partitions instead of the "old" {{ic|/dev/sd*}} and {{ic|/dev/hd*}} scheming. It has the advantage of detecting partitions by their unique UUIDs, which is needed by some people booting with complicated partition setups.<br />
<br />
UUIDs are used by default in the recent versions of GRUB2 - there is no downside in it anyway except that you need to re-generate the {{ic|grub.cfg}} file every time you resize or reformat your partitions. Remember this when modifying partitions with Live-CD.<br />
<br />
The recent versions of GRUB2 use UUIDs by default. You can re-enable the use of UUIDS by simply commenting the UUID line (this is also what it looks like by default):<br />
#GRUB_DISABLE_LINUX_UUID=true<br />
you can also just set the value as {{ic|false}} as shown here:<br />
GRUB_DISABLE_LINUX_UUID=false<br />
<br />
Either way, do not forget to generate the changes:<br />
grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
==== Using Labels ====<br />
<br />
It is possible to use labels, human-readable strings attached to filesystems, by using the {{ic|--label}} option to {{ic|search}}. First of all, label your existing partition:<br />
# tune2fs -L a <LABEL> <PARTITION><br />
<br />
Then, add an entry using labels. An example of this:<br />
<br />
menuentry "Arch Linux, session texte" {<br />
search --label --no-floppy --set=root archroot<br />
linux /boot/vmlinuz-linux root=/dev/disk/by-label/archroot ro<br />
initrd /boot/initramfs-linux.img<br />
}<br />
<br />
==== Recall previous entry ====<br />
<br />
GRUB2 can remember the last entry you booted from and use this as the default entry to boot from next time. This is useful if you have multiple kernels (i.e., the current Arch one and the LTS kernel as a fallback option) or operating systems. To do this, edit {{ic|/etc/default/grub}} and change the setting of {{ic|GRUB_DEFAULT}}:<br />
<br />
GRUB_DEFAULT=saved<br />
<br />
This ensures that GRUB will default to the saved entry. To enable saving the selected entry, add the following line to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_SAVEDEFAULT=true<br />
<br />
{{Note|Manually added menu items, eg Windows in {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} , will need {{ic|savedefault}} added. Remember to regenerate your configuration file.}}<br />
<br />
==== Security ====<br />
<br />
If you want to secure GRUB2 so it is not possible for anyone to change boot parameters or use the command line, you can add a user/password combination to GRUB2's configuration files. To do this, run the command {{ic|grub-mkpasswd_pbkdf2}}. Enter a password and confirm it. The output will look like this:<br />
<br />
{{bc|<nowiki><br />
Your PBKDF2 is grub.pbkdf2.sha512.10000.C8ABD3E93C4DFC83138B0C7A3D719BC650E6234310DA069E6FDB0DD4156313DA3D0D9BFFC2846C21D5A2DDA515114CF6378F8A064C94198D0618E70D23717E82.509BFA8A4217EAD0B33C87432524C0B6B64B34FBAD22D3E6E6874D9B101996C5F98AB1746FE7C7199147ECF4ABD8661C222EEEDB7D14A843261FFF2C07B1269A</nowiki>}}Then, add the following to {{ic|/etc/grub.d/00_header}}:<br />
{{bc|<nowiki>cat << EOF<br />
<br />
set superusers="username"<br />
password_pbkdf2 username <password><br />
<br />
EOF</nowiki>}}<br />
where {{ic|<password>}} is the string generated by {{ic|grub-mkpasswd_pbkdf2}}.<br />
<br />
Regenerate your configuration file. Your GRUB2 command line, boot parameters and all boot entries are now protected.<br />
<br />
This can be relaxed and further customized with more users as described in the "Security" part of [https://www.gnu.org/software/grub/manual/grub.html#Security the GRUB manual].<br />
<br />
==== Root Encryption ====<br />
<br />
To let GRUB2 automatically add the kernel parameters for root encryption,<br />
add {{ic|1=cryptdevice=/dev/yourdevice:label}} to {{ic|GRUB_CMDLINE_LINUX}} in {{ic|/etc/defaults/grub}}.<br />
<br />
Example with root mapped to {{ic|/dev/mapper/root}}:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:root"<br />
<br />
Also, disable the usage of UUIDs for the rootfs:<br />
<br />
GRUB_DISABLE_LINUX_UUID=true<br />
<br />
Regenerate the configuration.<br />
<br />
=== Booting an ISO Directly From GRUB2 ===<br />
Edit {{ic|/etc/grub.d/40_custom}} or {{ic|/boot/grub/custom.cfg}} to add an entry for the target ISO. When finished, update the GRUB menu as with the usual {{ic|grub-mkconfig -o /boot/grub/grub.cfg}} (as root).<br />
<br />
==== Arch ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk/partition number of the isofile. Also adjust the {{ic|img_dev}} line to match this same location. However, if booting the ISO from USB on a computer which also has one internal HDD, then it needs to be {{ic|hd0,Y}} with {{ic|sdbY}}, instead of {{ic|sdaY}}.}}<br />
<br />
menuentry "Archlinux-2011.08.19-netinstall-x86_64.iso" {<br />
set isofile="/archives/archlinux-2011.08.19-netinstall-x86_64.iso"<br />
loopback loop (hd0,7)$isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisolabel=ARCH_201108 img_dev=/dev/sda7 img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
<br />
==== Ubuntu ISO ====<br />
{{Note|Be sure to adjust the {{ic|hdX,Y}} in the third line to point to the correct disk or partition number of the ISO file.}}<br />
<br />
menuentry "ubuntu-12.04-desktop-amd64.iso" {<br />
set isofile="/path/to/ubuntu-12.04-desktop-amd64.iso"<br />
loopback loop (hdX,Y)$isofile<br />
linux (loop)/casper/vmlinuz boot=casper iso-scan/filename=$isofile quiet noeject noprompt splash --<br />
initrd (loop)/casper/initrd.lz<br />
}<br />
<br />
== Using the command shell ==<br />
<br />
Since the MBR is too small to store all GRUB2 modules, only the menu and a few basic commands reside there. The majority of GRUB2 functionality remains in modules in {{ic|/boot/grub}}, which are inserted as needed. In error conditions (e.g. if the partition layout changes) GRUB2 may fail to boot. When this happens, a command shell may appear.<br />
<br />
GRUB2 offers multiple shells/prompts. If there is a problem reading the menu but the bootloader is able to find the disk, you will likely be dropped to the "normal" shell:<br />
sh:grub><br />
<br />
If there is a more serious problem (e.g. GRUB cannot find required files), you may instead be dropped to the "rescue" shell:<br />
grub rescue><br />
<br />
The rescue shell is a restricted subset of the normal shell, offering much less functionality. If dumped to the rescue shell, first try inserting the "normal" module, then starting the "normal" shell:<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
grub rescue> insmod (hdX,Y)/boot/grub/i386-pc/normal.mod<br />
rescue:grub> normal<br />
<br />
=== Pager support ===<br />
<br />
GRUB2 supports pager for reading commands that provide long output (like the help command). This works only in normal shell mode and not in rescue mode. To enable pager, in GRUB2 command shell type:<br />
sh:grub> set pager=1<br />
<br />
== GUI configuration tools ==<br />
<br />
Following package may be installed from [[AUR]]<br />
* [https://aur.archlinux.org/packages.php?ID=44020 grub-customizer] (requires gettext gksu gtkmm hicolor-icon-theme openssl)<br />
*:Customize the bootloader (GRUB2 or BURG)<br />
* [http://kde-apps.org/content/show.php?content=139643 grub2-editor] (requires kdelibs)<br />
*:A KDE4 control module for configuring the GRUB2 bootloader<br />
* [http://kde-apps.org/content/show.php?content=137886 kcm-grub2] (requires kdelibs python2-qt kdebindings-python)<br />
*:This Kcm module manages the most common settings of Grub2.<br />
* [http://sourceforge.net/projects/startup-manager/ startupmanager] (requires gnome-python imagemagick yelp python2 xorg-xrandr)<br />
*:GUI app for changing the settings of GRUB, GRUB2, Usplash and Splashy<br />
<br />
== parttool or legacy hide/unhide ==<br />
<br />
If you have a Windows 9x paradigm with hidden C:\ disks GRUB Legacy had the hide/unhide feature. In GRUB2 this has been replaced by {{ic|parttool}}. For example, to boot the third C:\ disk of three Windows 9x installations on the CLI enter the CLI and:<br />
parttool hd0,1 hidden+ boot-<br />
parttool hd0,2 hidden+ boot-<br />
parttool hd0,3 hidden- boot+<br />
set root=hd0,3<br />
chainloader +1<br />
boot<br />
<br />
== Using the rescue console ==<br />
<br />
See [[#Using the command shell]] first. If unable to activate the standard shell, one possible solution is to boot using a live CD or some other rescue disk to correct configuration errors and reinstall GRUB. However, such a boot disk is not always available (nor necessary); the rescue console is surprisingly robust.<br />
<br />
The available commands in GRUB rescue include {{ic|insmod}}, {{ic|ls}}, {{ic|set}}, and {{ic|unset}}. This example uses {{ic|set}} and {{ic|insmod}}. {{ic|set}} modifies variables and {{ic|insmod}} inserts new modules to add functionality.<br />
<br />
Before starting, the user must know the location of their {{ic|/boot}} partition (be it a separate partition, or a subdirectory under their root):<br />
grub rescue> set prefix=(hdX,Y)/boot/grub<br />
<br />
where X is the physical drive number and Y is the partition number.<br />
<br />
To expand console capabilities, insert the {{ic|linux}} module:<br />
grub rescue> insmod (hdX,Y)/boot/grub/linux.mod<br />
<br />
{{Note|With a separate boot partition, omit {{ic|/boot}} from the path, (i.e. type {{ic|1=set prefix=(hdX,Y)/grub}} and {{ic|insmod (hdX,Y)/grub/linux.mod}}).}}<br />
<br />
This introduces the {{ic|linux}} and {{ic|initrd}} commands, which should be familiar (see [[#Configuration]]).<br />
<br />
An example, booting Arch Linux:<br />
set root=(hd0,5)<br />
linux /boot/vmlinuz-linux root=/dev/sda5<br />
initrd /boot/initramfs-linux.img<br />
boot<br />
<br />
With a separate boot partition, again change the lines accordingly:<br />
set root=(hd0,5)<br />
linux /vmlinuz-linux root=/dev/sda6<br />
initrd /initramfs-linux.img<br />
boot<br />
<br />
After successfully booting the Arch Linux installation, users can correct {{ic|grub.cfg}} as needed and then reinstall GRUB2.<br />
<br />
to reinstall GRUB2 and fix the problem completely, changing {{ic|/dev/sda}} if needed. See [[#Bootloader installation]] for details.<br />
<br />
== Combining the use of UUIDs and basic scripting ==<br />
<br />
If you like the idea of using UUIDs to avoid unreliable BIOS mappings or are struggling with GRUB's syntax, here is an example boot menu item that uses UUIDs and a small script to direct GRUB to the proper disk partitions for your system. All you need to do is replace the UUIDs in the sample with the correct UUIDs for your system. The example applies to a system with a boot and root partition. You will obviously need to modify the GRUB configuration if you have additional partitions:<br />
<br />
menuentry "Arch Linux 64" {<br />
# Set the UUIDs for your boot and root partition respectively<br />
set the_boot_uuid=ece0448f-bb08-486d-9864-ac3271bd8d07<br />
set the_root_uuid=c55da16f-e2af-4603-9e0b-03f5f565ec4a<br />
<br />
# (Note: This may be the same as your boot partition)<br />
<br />
# Get the boot/root devices and set them in the root and grub_boot variables<br />
search --fs-uuid --no-floppy --set=root $the_root_uuid<br />
search --fs-uuid --no-floppy --set=grub_boot $the_boot_uuid<br />
<br />
# Check to see if boot and root are equal.<br />
# If they are, then append /boot to $grub_boot (Since $grub_boot is actually the root partition)<br />
if [ $the_boot_uuid == $the_root_uuid] ; then<br />
set grub_boot=$grub_boot/boot<br />
fi<br />
<br />
# $grub_boot now points to the correct location, so the following will properly find the kernel and initrd<br />
linux ($grub_boot)/vmlinuz-linux root=/dev/disk/by-uuid/$uuid_os_root ro<br />
initrd ($grub_boot)/initramfs-linux.img<br />
}<br />
<br />
== Troubleshooting ==<br />
<br />
Any troubleshooting should be added here.<br />
<br />
=== Enable GRUB2 debug messages ===<br />
<br />
Add:<br />
<br />
set pager=1<br />
set debug=all<br />
<br />
to {{ic|grub.cfg}}.<br />
<br />
=== Correct GRUB2 No Suitable Mode Found Error ===<br />
<br />
If you get this error when booting any menuentry:<br />
<br />
error: no suitable mode found<br />
Booting however<br />
<br />
Then you need to initialize GRUB2 graphical terminal ({{ic|gfxterm}}) with proper video mode ({{ic|gfxmode}}) in GRUB2. This video mode is passed by GRUB2 to the linux kernel via 'gfxpayload'. In case of UEFI systems, if the GRUB2 video mode is not initialized, no kernel boot messages will be shown in the terminal (atleast until KMS kicks in).<br />
<br />
Copy {{ic|/usr/share/grub/unicode.pf2}} to ${GRUB2_PREFIX_DIR} ({{ic|/boot/grub/}} in case of BIOS and UEFI systems). If GRUB2 UEFI was installed with {{ic|1=--boot-directory=/boot/efi/EFI}} set, then the directory is {{ic|/boot/efi/EFI/grub/}}:<br />
<br />
# cp /usr/share/grub/unicode.pf2 ${GRUB2_PREFIX_DIR}<br />
<br />
If {{ic|/usr/share/grub/unicode.pf2}} does not exist, install {{Pkg|bdf-unifont}}, create the {{ic|unifont.pf2}} file and then copy it to {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}:<br />
<br />
# grub-mkfont -o unicode.pf2 /usr/share/fonts/misc/unifont.bdf<br />
<br />
Then, in the {{ic|grub.cfg}} file, add the following lines to enable GRUB2 to pass the video mode correctly to the kernel, without of which you will only get a black screen (no output) but booting (actually) proceeds successfully without any system hang.<br />
<br />
BIOS systems:<br />
<br />
insmod vbe<br />
<br />
UEFI systems:<br />
<br />
insmod efi_gop<br />
insmod efi_uga<br />
<br />
After that add the following code (common to both BIOS and UEFI):<br />
<br />
insmod font<br />
<br />
if loadfont ${prefix}/fonts/unicode.pf2<br />
then<br />
insmod gfxterm<br />
set gfxmode=auto<br />
set gfxpayload=keep<br />
terminal_output gfxterm<br />
fi<br />
<br />
As you can see for gfxterm (graphical terminal) to function properly, {{ic|unicode.pf2}} font file should exist in {{ic|${GRUB2_PREFIX_DIR<nowiki>}</nowiki>}}.<br />
<br />
=== msdos-style error message ===<br />
<br />
grub-setup: warn: This msdos-style partition label has no post-MBR gap; embedding won't be possible!<br />
grub-setup: warn: Embedding is not possible. GRUB can only be installed in this setup by using blocklists.<br />
However, blocklists are UNRELIABLE and its use is discouraged.<br />
grub-setup: error: If you really want blocklists, use --force.<br />
<br />
This error may occur when you try installing GRUB2 in a VMware container. Read more about it [https://bbs.archlinux.org/viewtopic.php?pid=581760#p581760 here]. It happens when the first partition starts just after the MBR (block 63), without the usual space of 1 MiB (2048 blocks) before the first partition. Read [[#MBR_aka_msdos_partitioning_specific_instructions]]<br />
<br />
=== UEFI GRUB2 drops to shell ===<br />
<br />
If GRUB loads but drops you into the rescue shell with no errors, it may be because of a missing or misplaced {{ic|grub.cfg}}. This will happen if GRUB2 UEFI was installed with {{ic|--boot-directory}} and {{ic|grub.cfg}} is missing OR if the partition number of the boot partition changed (which is hard-coded into the {{ic|grubx64.efi}} file).<br />
<br />
=== UEFI GRUB2 not loaded ===<br />
In some cases the EFI may fail to load GRUB correctly. Provided everything is set up correctly, the output of:<br />
efibootmgr -v<br />
might look something like this:<br />
BootCurrent: 0000<br />
Timeout: 3 seconds<br />
BootOrder: 0000,0001,0002<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\efi\grub\grub.efi)<br />
Boot0001* Shell HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\EfiShell.efi)<br />
Boot0002* Festplatte BIOS(2,0,00)P0: SAMSUNG HD204UI<br />
If everything works correctly, the EFI would now automatically load GRUB.<br />
<br />
If the screen only goes black for a second and the next boot option is tried afterwards, according to [https://bbs.archlinux.org/viewtopic.php?pid=981560#p981560 this post], moving GRUB to the partition root can help. The boot option has to be deleted and recreated afterwards. The entry for GRUB should look like this then:<br />
Boot0000* Grub HD(1,800,32000,23532fbb-1bfa-4e46-851a-b494bfe9478c)File(\grub.efi)<br />
<br />
=== Invalid signature ===<br />
If trying to boot Windows results in an "invalid signature" error, e.g. after reconfiguring partitions or adding additional hard drives, (re)move GRUB's device configuration and let it reconfigure:<br />
# mv /boot/grub/device.map /boot/grub/device.map-old<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
{{ic|grub-mkconfig}} should now mention all found boot options, including Windows. If it works, remove {{ic|/boot/grub/device.map-old}}.<br />
<br />
=== Restore GRUB Legacy ===<br />
<br />
* Move GRUB2 files out of the way:<br />
<br />
# mv /boot/grub /boot/grub.nonfunctional<br />
<br />
* Copy GRUB Legacy back to {{ic|/boot}}:<br />
<br />
# cp -af /boot/grub-legacy /boot/grub<br />
<br />
* Replace MBR and next 62 sectors of sda with backed up copy<br />
<br />
{{Warning|This command also restores the partition table, so be careful of overwriting a modified partition table with the old one. It '''will''' mess up your system.}}<br />
<br />
# dd if=/path/to/backup/first-sectors of=/dev/sdX bs=512 count=1<br />
<br />
A safer way is to restore only the MBR boot code use:<br />
<br />
# dd if=/path/to/backup/mbr-boot-code of=/dev/sdX bs=446 count=1<br />
<br />
== References ==<br />
<br />
# Official GRUB2 Manual - https://www.gnu.org/software/grub/manual/grub.html<br />
# Ubuntu wiki page for GRUB2 - https://help.ubuntu.com/community/Grub2<br />
# GRUB2 wiki page describing steps to compile for UEFI systems - https://help.ubuntu.com/community/UEFIBooting<br />
# Wikipedia's page on [[Wikipedia:BIOS Boot partition|BIOS Boot partition]]<br />
<br />
== External Links ==<br />
<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_bios.sh A Linux Bash Shell script to compile and install GRUB(2) for BIOS from BZR Source]<br />
# [https://github.com/the-ridikulus-rat/My_Shell_Scripts/blob/master/grub/grub_uefi.sh A Linux Bash Shell script to compile and install GRUB(2) for UEFI from BZR Source]</div>Lfxgroovehttps://wiki.archlinux.org/index.php?title=Ruby_on_Rails&diff=200957Ruby on Rails2012-05-10T18:37:51Z<p>Lfxgroove: Added small note about using rvmsudo to do the rvm install ree part</p>
<hr />
<div>[[Category:Web Server]]<br />
{{i18n|Ruby on Rails}}<br />
<br />
[http://rubyonrails.org/ Ruby on Rails], often shortened to Rails or RoR, is an open source web application framework for the Ruby programming language. It is intended to be used with an Agile development methodology that is used by web developers for rapid development.<br />
<br />
This document describes how to set up the Ruby on Rails Framework on an Arch Linux system.<br />
<br />
Ruby on Rails requires [[Ruby]] to be installed, so read that article first for installation instructions.<br />
<br />
== Option A: Installation via RubyGems (Recommended) ==<br />
<br />
{{Box Note | If this command is run without being root (using sudo or otherwise), the gem will be installed into the home directory of the user.}}<br />
<br />
# gem install rails<br />
<br />
Building the documentation takes a while. If you want to skip it, append the parameters --no-ri --no-rdoc to the install command.<br />
# gem install rails --no-ri --no-rdoc<br />
<br />
=== Updating Gems ===<br />
<br />
gem is a package manager for Ruby modules, somewhat like pacman is to Arch Linux. To update your gems, simply run:<br />
# gem update<br />
<br />
== Option B: Installing via the AUR ==<br />
<br />
{{Warning|This is not recommended, as this might not include the latest Rails version, and additional dependencies may be introduced that may require you to run {{Ic|gem install}} anyway.}}<br />
There is a {{AUR|rails}} package available in the [[AUR]]. Note that this is not in an [[Official Repositories|official repository]], so you will need to [[AUR#Build_the_package|build it manually]].<br />
<br />
== Configuration ==<br />
<br />
Rails is bundled with a basic HTTP server called WeBrick. You can create a test application to test it. First, create an application with the rails command:<br />
<br />
$ rails new testapp_name<br />
<br />
This makes a new folder in your current working directory. Next start the web server. It listens on port 3000 by default:<br />
<br />
$ cd testapp_name<br />
$ rails server<br />
<br />
Finally open your server address on port 3000 in your web browser. For example, if you are working on your local machine, visit http://localhost:3000.<br />
<br />
A test-page should shown greeting you "Welcome aboard".<br />
<br />
== Web servers ==<br />
<br />
While the default Ruby On Rails HTTP server (WeBrick) is convenient for basic development it is not recommended for production use. Here are some suitable alternatives:<br />
<br />
=== Mongrel ===<br />
<br />
Mongrel is a drop-in replacement for WeBrick, that can be run in precisely the same way, but offers better performance.<br />
<br />
First install the Mongrel gem:<br />
# gem install mongrel<br />
<br />
Then start it using:<br />
# mongrel_rails start<br />
<br />
Alternatively, you can just run "ruby script/server" again, as it replaces WeBrick by default.<br />
<br />
Generally, Mongrel is used in a production environment by running multiple instances of mongrel_rails, which are load-balanced behind an [[Nginx]] or [[Apache]] reverse proxy. However, you might find Phusion Passenger (see below) a much simpler solution for running a production environment.<br />
<br />
=== Apache/Nginx (using Phusion Passenger) ===<br />
<br />
[http://www.modrails.com/ Passenger] also known as {{ic|mod_rails}} is a module available for [[Nginx]] and [[Apache]], that greatly simplifies setting up a Rails server environment.<br />
<br />
Start by installing the Passenger gem:<br />
# gem install passenger<br />
<br />
If you are aiming to use [[Apache]] with Passenger, run:<br />
# passenger-install-apache2-module<br />
<br />
For [[Nginx]]:<br />
# passenger-install-nginx-module<br />
<br />
The installer will provide you with any additional information regarding the installation (such as installing additional libraries).<br />
<br />
{{Note|See [[NginX#Ruby_Integration_(Ruby_on_Rails_and_Rack-based)]] for more information on configuring a Rails Nginx-Passenger web stack.}}<br />
<br />
== Databases ==<br />
<br />
Most web applications will need to interact with some sort of database. ActiveRecord (the ORM used by Rails to provide database abstraction) supports several database vendors, the most popular of which are MySQL, SQLite, and PostgreSQL.<br />
<br />
=== SQLite ===<br />
<br />
SQLite is the default lightweight database for Ruby on Rails. To enable SQLite, simply install {{Pkg|sqlite3}}.<br />
<br />
=== PostgreSQL ===<br />
<br />
(Stub.)<br />
<br />
Install {{Pkg|postgresql}}.<br />
<br />
=== MySQL ===<br />
<br />
{{Note|You must first install [[MySQL]] with the appropriate headers in {{ic|/usr/include}} (just installing {{Pkg|mysql}} is fine) before attempting to install the Ruby MySQL extensions.}}<br />
<br />
Please refer to [[MySQL]] on how to install MySQL Server.<br />
<br />
A gem with some native extensions is required, probably best installed as root:<br />
# sudo gem install mysql<br />
<br />
You can generate a rails application configured for MySQL by using the {{Ic|-d}} parameter:<br />
$ rails new testapp_name -d mysql<br />
<br />
You then need to edit config/database.yml. Rails uses different databases for development, testing, production and other environments. Here is an example development configuration for MySQL running on localhost:<br />
<br />
development:<br />
adapter: mysql<br />
database: my_application_database<br />
username: development<br />
password: my_secret_password<br />
<br />
Note that you do not have to actually create the database using MySQL, as this can be done via Rails with:<br />
# rake db:create<br />
<br />
If no errors are shown, then your database has been created and Rails can talk to your MySQL database.<br />
<br />
== Option C: The Perfect Rails Setup ==<br />
<br />
''Phusion Passenger running multiple Ruby versions.''<br />
<br />
* [http://www.archlinux.org/ Archlinux]: A simple, lightweight distribution. ;)<br />
* [http://www.nginx.org/ Nginx]: A fast and lightweight '''web server''' with a strong focus on high concurrency, performance and low memory usage.<br />
* [http://www.modrails.com/ Passenger] (a.k.a. mod_rails or mod_rack): Supports both Apache and Nginx web servers. It makes deployment of Ruby web applications, such as those built on Ruby on Rails web framework, a breeze.<br />
* [http://www.rubyenterpriseedition.com/ Ruby Enterprise Edition] (REE): Passenger allows Ruby on Rails applications to use about 33% less memory, when used in combination with REE.<br />
* [http://rvm.beginrescueend.com/ Ruby Version Manager] (RVM): A command-line tool which allows you to easily install, manage, and work with multiple Ruby environments from interpreters to sets of gems. RVM lets you deploy each project with its own completely self-contained and dedicated environment —from the specific version of ruby, all the way down to the precise set of required gems to run your application—.<br />
* [http://sqlite.org/ SQLite]: The default lightweight '''database''' for Ruby on Rails.<br />
<br />
=== Step 0: SQLite ===<br />
<br />
Easy as:<br />
$ sudo pacman -S sqlite3<br />
<br />
{{note|Of course SQLite is not critical in this setup, you can use MySQL and PostgreSQL as well.}}<br />
<br />
=== Step 1: RVM ===<br />
<br />
Make a multi-user [[RVM]] installation as specified [[RVM#Multi-user_installation|here]].<br />
<br />
In the 'adding users to the rvm group' step, do<br />
$ sudo usermod -a -G rvm http<br />
$ sudo usermod -a -G rvm nobody<br />
. http and nobody are the users related to Nginx and Passenger, respectively.<br />
<br />
{{note|Maybe adding the 'nodody' user to the 'rvm' group is not necessary.}} <br />
<br />
=== Step 2: Rubies ===<br />
<br />
Once you have a working RVM installation in your hands, it is time to install the Ruby Enterprise Edition interpreter<br />
{{Note|During the installation of Ruby Enterprise Edition patches will be applied. Consider installing '''base-devel''' beforehand.}}<br />
{{Note|If you installed RVM with the multiuser guide, you seem to need to prepend your commands with rvmsudo, ie: rvmsudo rvm install ree.}}<br />
<br />
$ rvm install ree<br />
. Also take the chance to include other interpreters you want to use, like the last Ruby version<br />
$ rvm install 1.9.3<br />
<br />
==== Advice ====<br />
<br />
I have found useful to delete the 'global' gemsets of the environments that have web applications. Their gems were somehow interfering with Passenger. Do not do<br />
$ rvm ree do gemset delete global<br />
$ rvm 1.9.3 do gemset delete global<br />
now, but consider this later if you encounter complications.<br />
<br />
=== Step 3: Nginx with Passenger support ===<br />
<br />
Do not install Nginx via pacman. This web server does not support modules as Apache, so it must be compiled from source with the functionality of ''mod_rails'' (Passenger). Fortunately this is straightforward thanks to the passenger gem. Get it:<br />
$ rvm use ree<br />
$ gem install passenger<br />
. The gem will be put into the 'default' gemset. Now execute the following script:<br />
$ rvmsudo passenger-install-nginx-module<br />
. It will download the sources of Nginx, compile and install it for you. It will guide you through all the process. (The default location for Nginx is /opt/nginx.)<br />
<br />
After completion, the script will require you to add two lines into the 'http block' at /opt/nginx/conf/nginx.conf that look like:<br />
http { <br />
...<br />
passenger_root /usr/local/rvm/gems/ree-1.8.7-2011.03/gems/passenger-3.0.9;<br />
passenger_ruby /usr/local/rvm/wrappers/ree-1.8.7-2011.03/ruby;<br />
...<br />
}<br />
<br />
For everything that is not Ruby, use [[Nginx]] as usual to serve static pages, PHP and Python. Check the wiki page for more information.<br />
<br />
To enable the Nnginx service by default at start-up just add {{Ic|nginx}} to the {{Ic|DAEMONS}} array in {{ic|/etc/rc.conf}}:<br />
DAEMONS=(ntpd syslog-ng ... nginx)<br />
<br />
{{note|It is possible that your Nginx installation has not come with an init script; check your /etc/rc.d/ directory for a file called ''nginx'', if that is your case manually create it. Help yourself with [[Nginx/Init_script]]. If you installed nginx to another location, such as /opt/nginx, you will need to edit the init script accordingly.}}<br />
<br />
=== Step 4: Gemsets and Apps ===<br />
<br />
For each Rails application you should have a gemset. Suppose that you want to try [http://refinerycms.com RefineryCMS] against [http://www.browsercms.org BrowserCMS], two open-source Content Management Systems based on Rails. Then you should do:<br />
$ rvm use ree@refinery --create<br />
$ gem install rails -v 3.0.11<br />
$ gem install passenger<br />
$ gem install refinerycms refinerycms-i18n sqlite3<br />
Deploy a RefineryCMS instance called ''refineria'':<br />
$ cd /srv/http/<br />
$ rvmsudo refinerycms refineria<br />
Again:<br />
$ rvm use 1.9.3@browser --create<br />
$ gem install passenger<br />
$ gem install browsercms sqlite3<br />
Deploy a BrowserCMS instance called ''navegador'':<br />
$ cd /srv/http/<br />
$ rvmsudo browsercms demo navegador<br />
$ cd /srv/http/navegador<br />
$ rvmsudo rake db:install<br />
<br />
=== Passenger for Nginx and Passenger Standalone ===<br />
<br />
Observe that the passenger gem was installed three times and with different intentions; in the environments<br />
* ''ree'' => for Nginx,<br />
* ''ree@refinery'' => Standalone, and<br />
* ''1.9.3@browser'' => Standalone.<br />
<br />
The strategy is to combine Passenger for Nginx with Passenger Standalone. One must first identify the Ruby environment (interpreter plus gemset) that one uses the most; in this setup the REE interpreter and the default gemset were selected. One then proceeds with setting up Passenger for Nginx to use that environment. All applications that are to use a different Ruby version and/or gemset can be served separately through Passenger Standalone and hook into the main web server via a reverse proxy configuration.<br />
<br />
=== Step 5: .rvmrc files and ownerships ===<br />
<br />
This step is crucial for the correct behaviour of the setup. RVM seeks for .rvmrc files when changing folders; if it finds one, it reads it. In these files normally one stores a line like<br />
rvm <ruby_version>@<gemset_name><br />
so the specified environment is set at the entrance of applications' root folder.<br />
<br />
Create /srv/http/refineria/.rvmrc doing<br />
sudo sh -c 'echo "rvm ree@refinery" > /srv/http/refineria/.rvmrc'<br />
, and /srv/http/navegador/.rvmrc with<br />
sudo sh -c 'echo "rvm 1.9.3@browser" > /srv/http/navegador/.rvmrc'<br />
You have to enter to both application root folders now, because every first time that RVM finds a .rvmrc it asks you if you trust the given file, consequently you must validate the two files you have just created.<br />
<br />
These files aid the programs involved to find the correct gems.<br />
<br />
Apart, if applications' files and folders are not owned by the right user you will face database write-access problems. The use of rvmsudo produces ''root''-owned archives when generated by Rails; in the other hand, ''nobody'' is the user for Passenger —if you have not changed it—: who will use and should posses them. Fix this doing<br />
$ sudo chown -R nobody.nobody /srv/http/refineria /srv/http/navegador<br />
<br />
=== Step 6: Reverse proxies ===<br />
<br />
You have to start the Passenger Standalone web servers for your applications. So, do<br />
$ cd /srv/http/refineria<br />
$ rvmsudo passenger start --socket refineria.socket -d<br />
and<br />
$ cd /srv/http/navegador<br />
$ rvmsudo passenger start --socket navegador.socket -d<br />
. The first time that you run a Passenger Standalone it will perform a minor installation.<br />
<br />
Note that you are using ''unix domain'' sockets instead of the commonly-used ''TCP'' sockets; it turns out that unix domain are significantly faster than TCP sockets.<br />
<br />
==== Launch Passenger Standalone daemons at system start-up ====<br />
<br />
''Coming soon!''<br />
<br />
=== Step 7: Deployment ===<br />
<br />
Once again edit /opt/nginx/conf/nginx.conf to include some vital instructions:<br />
<br />
<pre><br />
## RefineryCMS ##<br />
<br />
upstream refineria_upstream {<br />
server unix:/srv/http/refineria/refineria.socket;<br />
}<br />
<br />
server {<br />
server_name refinery.domain.com;<br />
root /srv/http/refineria/public;<br />
location / {<br />
proxy_pass http://refineria_upstream;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
<br />
## BrowserCMS ##<br />
<br />
upstream navegador_upstream {<br />
server unix:/srv/http/navegador/navegador.socket;<br />
}<br />
<br />
server {<br />
server_name browser.domain.com;<br />
root /srv/http/navegador/public;<br />
location / {<br />
proxy_pass http://navegador_upstream;<br />
proxy_set_header Host $host;<br />
}<br />
}<br />
</pre><br />
<br />
At this point you are in conditions to run Nginx with:<br />
<br />
$ sudo rc.d start nginx<br />
<br />
and to access both CMSs through ''refinery.domain.com'' and ''browser.domain.com''.<br />
<br />
=== References ===<br />
<br />
* http://beginrescueend.com/integration/passenger<br />
* http://blog.phusion.nl/2010/09/21/phusion-passenger-running-multiple-ruby-versions<br />
<br />
== See also ==<br />
<br />
* [[Ruby]]<br />
* [[Nginx]]<br />
* [[LAMP]]<br />
* [[MySQL]]<br />
<br />
== References ==<br />
<br />
* Ruby on Rails http://rubyonrails.org/download.<br />
* Mongrel http://mongrel.rubyforge.org.</div>Lfxgroove