Difference between revisions of "Netcfg"

From ArchWiki
Jump to: navigation, search
(Step 2)
(netcfg was deprecated in favour of netctl, just redirect there)
 
(311 intermediate revisions by 92 users not shown)
Line 1: Line 1:
[[Category:Networking (English)]]
+
#REDIRECT [[Netctl]]
{{i18n_links_start}}
 
{{i18n_entry|English|Network Profiles}}
 
{{i18n_entry|简体中文|Netcfg2网络配置}}
 
{{i18n_entry|Türkçe|Ağ Profilleri}}
 
{{i18n_links_end}}
 
 
 
==Quickstart==
 
===Step 1===
 
# pacman -Sy netcfg
 
 
 
===Step 2===
 
Copy an example configuration from /etc/network.d/examples/  to /etc/network.d/mynetwork. You may use another name instead of "mynetwork".
 
 
 
Depending on your security and connection, use the following examples from /etc/network.d/examples/
 
* '''WEP hex key'''  wireless-wep
 
* '''WEP string key''' wireless-wep-string-key
 
* '''WPA passphrase''' wireless-wpa
 
* '''WPA enterprise''' wireless-wpa-config
 
* '''WPA enterprise/passphrase''' wireless-wpa-configsection (new in netcfg 2.5)
 
* '''Wired connection - dhcp''' ethernet-dhcp
 
* '''Wired connection - static IP''' ethernet-static
 
* '''Wired connection - iproute configuration''' ethernet-iproute
 
 
 
===Step 3===
 
Modify your configuration file new configuration file, /etc/network.d/mynetwork
 
 
 
* Set INTERFACE= to your wireless or ethernet interface. This can be checked with ifconfig and iwconfig.
 
* '''Wireless''' - Make sure you set your ESSID and KEY correctly. Typos in these are common errors.
 
* '''Wireless - WPA Enterprise''' - You'll need to use an external wpa_supplicant configuration.
 
 
 
===Step 4===
 
To connect, simply execute:
 
# netcfg mynetwork
 
 
 
If it does not work, have a look at the [[Network Profiles#Troubleshooting|troubleshooting section]] for solutions and how to get help.
 
 
 
If all goes to plan, you can configure it to  [[Network Profiles#Step 4: Connecting on boot|connect automatically or on boot]].
 
 
 
==Step 1: Install==
 
Network profiles are handled by the bash scripts available in the netcfg package.
 
 
 
# pacman -Sy netcfg
 
 
 
For information relating to the latest development version of netcfg, see [[Network Profiles development]]
 
 
 
==Step 2: Create the profile(s)==
 
A profile is a single text file in /etc/network.d which defines variables used by netcfg. The file name will become the name of the profile, and can be anything you wish, it is not a setting involved in the connection.
 
 
 
The easiest way to create a new profile is to copy one of the example profiles from /etc/network.d/examples and edit it to fit with your network.
 
 
 
{{Box Note | Example profiles are located in /etc/network.d/examples/. Modifying an example from here is the best way to ensure that you have a configuration suitable for your version of netcfg. }}
 
 
 
{{Box Note | Your network information (e.g. wireless passkey) will be stored in plain text format, so you may want to change the permissions on the newly created /etc/network.d/*.conf file (e.g. <tt>chmod 0600 /etc/network.d/*.conf</tt> to make it readable by root only), depending upon how security conscious you are. }}
 
 
 
===Configuration Notes===
 
====Using a string WEP key====
 
This is for a STRING WEP key, not a HEX WEP key, not a WPA key.
 
KEY="s:Somepasskey"
 
 
 
====Ralink legacy drivers rt2500, rt2400 that use iwpriv====
 
There is no plans to add WPA support to these drivers. rt2x00 is supported, however, and will replace these.
 
 
 
If you must use them, create a shell script that runs the needed iwpriv commands and put its path in PRE_UP=""
 
 
 
====Passing arguments to iwconfig before connecting====
 
Simply:
 
 
 
IWCONFIG="<arguments>"
 
 
 
Where <arguments> can be any valid iwconfig argument. The script then runs "iwconfig $INTERFACE $IWCONFIG"
 
 
 
For example, setting bssid/ap mac:
 
IWCONFIG="ap 12:34:56:78:90:12"
 
 
 
This supercedes the IWOPTS and WEP_OPTS options which were incompletely implemented.
 
 
 
====Execute commands before/after interface up/down====
 
If your interface requires special actions prior/after the establishment/closure of a connection, you may use the '''PRE_UP''', '''POST_UP''', '''PRE_DOWN''', '''POST_DOWN''' properties.
 
 
 
For example, if you want to set your wlan card to operate in ad-hoc mode but you can only change it when the interface is down, you could use something like this:
 
 
 
PRE_UP="ifconfig wlan0 down; iwconfig wlan0 mode ad-hoc"
 
 
 
Or if you want to mount your network shares after a successful connection, you could use:
 
 
 
POST_UP="sleep 5; mount /mnt/shares/nexus/utorrent 2>/dev/null;"
 
 
 
{{Note|If the commands specified in these properties return anything other than 0 (success), netcfg aborts the current operation. So if you want to mount a certain network share that might not be available at the time of connection (thus returning an error), you could create a separate bash script with the mount commands and a "exit 0;" at the end. Alternatively you can add <nowiki>"|| true"</nowiki> to the end of the command that may fail.}}
 
 
 
==Step 3: Connect==
 
To connect to a profile just execute the following command ''as root'':
 
# netcfg <profile-name>
 
To disconnect from a profile:
 
# netcfg down <profile-name>
 
 
 
Where <profile-name> is the name of the file created in /etc/network.d. For example /etc/network.d/homewireless would simply have a profile name of homewireless
 
 
 
==Step 4: Connecting on boot==
 
===net-profiles===
 
<code>net-profiles</code> allows you to start some profiles on boot.
 
 
 
In order to do that you need to list the /etc/network.d/ profiles you want netcfg to try at boot in the <code>NETWORKS=()</code> line in /etc/rc.conf.
 
 
 
NETWORKS=(home mywireless)
 
 
 
You also need to add <code>net-profiles</code> to the DAEMONS array, eg: DAEMONS=(... '''net-profiles''' ...).
 
 
 
If you are only using a laptop, with little-to-no use of ethernet, you may want to delete the Network Daemon to resolve boot issues.
 
 
 
====Display a menu at boot====
 
<code>net-profiles</code> can also display a menu so you can pick which profile you want to set up. For that you just need to set NETWORKS= to menu:
 
 
 
NETWORKS=menu
 
 
 
or
 
 
 
NETWORKS=(menu)
 
 
 
(either will work). You can also access that menu at any time by running <code>netcfg-menu</code> in a terminal.
 
 
 
The dialog package is needed.
 
 
 
===Automatic detection===
 
====net-auto====
 
<code>net-auto</code> is the second boot-time script of the netcfg package. Its function is to determine automatically which profile should be started.
 
 
 
<code>net-auto</code> reads the AUTO_NETWORKS=() line in /etc/rc.conf. For example:
 
AUTO_NETWORKS=(auto-wireless wlan0)
 
 
 
Like <code>net-profiles</code> it needs to be added to the DAEMONS=() line, eg: DAEMONS=(... '''net-auto''' ...).
 
 
 
To run after boot:
 
# /usr/bin/netcfg-auto-wireless $interface
 
 
 
note: for this to work with a given profile, that profile MUST set the ESSID variable (which is not required to connect manually if a separate wpa_supplicant.conf is supplied.)
 
 
 
==Troubleshooting==
 
===Wireless connections===
 
For wireless connections, make sure the required drivers and firmwares are installed as explained in [[Wireless Setup]].
 
===netcfg error messages===
 
====Network unavailable====
 
This is typically one of:
 
* Out of range
 
* Driver issue (See Driver Quirks above)
 
* Trying to connect to a hidden network
 
 
 
If you know your network is hidden, set
 
SCAN=no
 
 
 
====Wireless Association failed====
 
This is typically one of:
 
* Out of range/reception
 
* Incorrect configuration
 
* Invalid key
 
* Driver problem (See Driver Quirks above)
 
 
 
If it is a range problem, increasing TIMEOUT= can help.
 
 
 
====Unable to get IP address with DHCP====
 
This is typically one of:
 
* Out of range/reception
 
 
 
Try increasing DHCP_TIMEOUT
 
 
 
====Not a valid connection, check spelling or look at examples====
 
You must set CONNECTION= to one of the connection types in /usr/lib/network/connections/. Alternatively use one of the provided configuration examples in /etc/network.d/examples.
 
 
 
===Driver Quirks (netcfg 2.1 and later)===
 
{{Box Note | You most likely do NOT need these. Ensure your configuration is correct before considering these. They are for a small range of drivers with unusual issues, many of them older versions. These are workarounds, not solutions. }}
 
 
 
Some drivers behave oddly and need workarounds to connect. These have to be enabled manually. They're best determined by reading the forums, seeing what others have used, and, if that fails, trial and error. They '''can''' be combined.
 
 
 
* prescan - Run "iwlist $INTERFACE scan" before attempting to connect (Some broadcom)
 
* preessid - Run "iwconfig $INTERFACE essid $ESSID" before attempting to connect. (Some ipw3945 and Intel PRO/Wireless 4965AGN)
 
* wpaessid - Same as previous, run before starting wpa_supplicant (ath9k)
 
* predown - Take interface down before association and then restore it after. (madwifi)
 
* postsleep - Sleep 1 second before checking if the association was successful
 
* postscan - Run "iwlist scan" after associating
 
 
 
For example
 
QUIRKS=(prescan preessid)
 
 
 
If you are having problems with DNS and DHCP, try adding to your profile:
 
DHCLIENT=no
 
This will tell netcfg to use dhcpcd instead of dhclient
 
 
 
If you get "Wireless Network Not Found" or "Association Failed" and have tried the above, try:
 
SCAN=no
 
 
 
===It still doesn't work, what do I do ?===
 
If the FAQs below didn't solve your problem the next best place to go is the forums, or the mailing list.
 
 
 
To be able to determine what's wrong, we need information so when you post, make sure that you provide the following output:
 
* '''''ALL OUTPUT FROM netcfg'''''
 
* '''''ALL OUTPUT FROM netcfg'''''
 
* '''''ALL OUTPUT FROM netcfg''''' - this is absolutely crucial to be able determine what went wrong. The message might be short or nonexistant, but it can mean a great deal.
 
* '''''Your /etc/network.d network profiles''''' - Also crucial as many problems are simple config issues. Feel free to censor your wireless key.
 
* '''''netcfg version'''''
 
* lsmod
 
* iwconfig
 
 
 
==GUI==
 
 
 
A Qt-based netcfg frontend called ArchAssistant exists. It proposes to manage & connect/disconnect profiles from a systray icon. Automatic wireless detection is also available. This tool is particularly useful for laptop users.
 
 
 
Links:
 
[http://aur.archlinux.org/packages.php?ID=15655 archassistant on AUR] | [http://www.kde-apps.org/content/show.php/ArchAssistant?content=76760 archassistant on kde-apps.org] | archassistant package on archlinux.fr [http://repo.archlinux.fr/i686/ i686] and [http://repo.archlinux.fr/x86_64/ x86_64]
 
 
 
There is also a relatively new gui to netcfg2 on qt-apps that does only network configuring.You can find it here: [http://www.qt-apps.org/content/show.php/netcfgGUI?content=99523].
 
 
 
==Supplementary tools==
 
 
 
There is a console tool for selecting wireless networks "in real-time" (in NetworkManager manner) called <code>wifi-select</code>. The tool is convenient for use in wifi-cafe or another places you are visiting for the first (and maybe the last) time. Then you don't need to create the file-profile for a new network, just type <code>sudo wifi-select wlan0</code> and choose the network you need.
 
 
 
The tool is currently packaged and available in [community] repository. To install, do <code>pacman -S wifi-select</code>.
 
 
 
It works as follows:
 
* parses <code>iwlist scan</code> results and presents list of networks along with its security settings (wpa/wep/none) using <code>dialog</code>
 
* if user selects network with existing profile -- just use this profile to connect with <code>netcfg</code>
 
* if user selects a new network (for example network from wifi-cafe he currently visited), <code>wifi-select</code> automatically generates new profile with corresponding <code>$SECURITY</code> and asks for the key (if needed). It uses DHCP as <code>$IP</code> by default
 
* then, if connection succeeds, profile is saved for later usage
 
* if connection fails, user is asked if he/she wants to keep generated profile for further usage (for example to change <code>$IP</code> to static or adjust some additional options)
 
 
 
Links:
 
[http://bbs.archlinux.org/viewtopic.php?id=63973 Forum thread] related to development of <code>wifi-select</code> |  [http://aur.archlinux.org/packages.php?ID=23471 wifi-select on AUR] | [http://hg.horna.org.ua/wifi-select/ wifi-select mercurial repository]
 
 
 
==FAQ==
 
===Why doesnt netcfg do ''x''?===
 
netcfg doesn't need to. It connects to networks.
 
 
 
But netcfg is super modular and re-usable. Have a look at /usr/lib/networks/ -- heaps of reusable functions for your own scripts.
 
 
 
===Why doesn't netcfg behave in this way? It makes more sense===
 
netcfg doesn't enforce any rules. It's task is to connect to networks. It doesn't impose any heuristics, like 'disconnect from wireless if ethernet is connected'.
 
 
 
If you want behaviour like that, it'd be really easy to write a separate tool over netcfg. See the question above.
 
 
 
===Do I still need ''x'' when I'm using netcfg?===
 
* /etc/hosts: Yes, you still need this, this is important. Don't remove your hostname from this otherwise you'll have some odd problems.
 
* HOSTNAME= in /etc/rc.conf: It's strongly recommended you keep this, otherwise no hostname will be set if a profile fails
 
* DAEMONS=(network) and INTERFACES=() in /etc/rc.conf: If you've setup all your networks with netcfg instead, yes, you can remove this. You can also safely remove lo, it's been moved into rc.sysinit.
 
* lo: This is now in rc.sysinit, you don't need to configure it anywhere.
 

Latest revision as of 15:26, 16 July 2013

Redirect to: