diff options
Diffstat (limited to 'doc/admin-guide/en-US/markdown/admin_settingup_clients.md')
| -rw-r--r-- | doc/admin-guide/en-US/markdown/admin_settingup_clients.md | 641 |
1 files changed, 641 insertions, 0 deletions
diff --git a/doc/admin-guide/en-US/markdown/admin_settingup_clients.md b/doc/admin-guide/en-US/markdown/admin_settingup_clients.md new file mode 100644 index 00000000000..85b28c9525f --- /dev/null +++ b/doc/admin-guide/en-US/markdown/admin_settingup_clients.md @@ -0,0 +1,641 @@ +Accessing Data - Setting Up GlusterFS Client +============================================ + +You can access gluster volumes in multiple ways. You can use Gluster +Native Client method for high concurrency, performance and transparent +failover in GNU/Linux clients. You can also use NFS v3 to access gluster +volumes. Extensive testing has be done on GNU/Linux clients and NFS +implementation in other operating system, such as FreeBSD, and Mac OS X, +as well as Windows 7 (Professional and Up) and Windows Server 2003. +Other NFS client implementations may work with gluster NFS server. + +You can use CIFS to access volumes when using Microsoft Windows as well +as SAMBA clients. For this access method, Samba packages need to be +present on the client side. + +Gluster Native Client +===================== + +The Gluster Native Client is a FUSE-based client running in user space. +Gluster Native Client is the recommended method for accessing volumes +when high concurrency and high write performance is required. + +This section introduces the Gluster Native Client and explains how to +install the software on client machines. This section also describes how +to mount volumes on clients (both manually and automatically) and how to +verify that the volume has mounted successfully. + +Installing the Gluster Native Client +------------------------------------ + +Before you begin installing the Gluster Native Client, you need to +verify that the FUSE module is loaded on the client and has access to +the required modules as follows: + +1. Add the FUSE loadable kernel module (LKM) to the Linux kernel: + + `# modprobe fuse` + +2. Verify that the FUSE module is loaded: + + `# dmesg | grep -i fuse ` + + `fuse init (API version 7.13)` + +### Installing on Red Hat Package Manager (RPM) Distributions + +To install Gluster Native Client on RPM distribution-based systems + +1. Install required prerequisites on the client using the following + command: + + `$ sudo yum -y install openssh-server wget fuse fuse-libs openib libibverbs` + +2. Ensure that TCP and UDP ports 24007 and 24008 are open on all + Gluster servers. Apart from these ports, you need to open one port + for each brick starting from port 24009. For example: if you have + five bricks, you need to have ports 24009 to 24013 open. + + You can use the following chains with iptables: + + `$ sudo iptables -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 24007:24008 -j ACCEPT ` + + `$ sudo iptables -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 24009:24014 -j ACCEPT` + + > **Note** + > + > If you already have iptable chains, make sure that the above + > ACCEPT rules precede the DROP rules. This can be achieved by + > providing a lower rule number than the DROP rule. + +3. Download the latest glusterfs, glusterfs-fuse, and glusterfs-rdma + RPM files to each client. The glusterfs package contains the Gluster + Native Client. The glusterfs-fuse package contains the FUSE + translator required for mounting on client systems and the + glusterfs-rdma packages contain OpenFabrics verbs RDMA module for + Infiniband. + + You can download the software at [][]. + +4. Install Gluster Native Client on the client. + + `$ sudo rpm -i glusterfs-3.3.0qa30-1.x86_64.rpm ` + + `$ sudo rpm -i glusterfs-fuse-3.3.0qa30-1.x86_64.rpm ` + + `$ sudo rpm -i glusterfs-rdma-3.3.0qa30-1.x86_64.rpm` + + > **Note** + > + > The RDMA module is only required when using Infiniband. + +### Installing on Debian-based Distributions + +To install Gluster Native Client on Debian-based distributions + +1. Install OpenSSH Server on each client using the following command: + + `$ sudo apt-get install openssh-server vim wget` + +2. Download the latest GlusterFS .deb file and checksum to each client. + + You can download the software at [][1]. + +3. For each .deb file, get the checksum (using the following command) + and compare it against the checksum for that file in the md5sum + file. + + `$ md5sum GlusterFS_DEB_file.deb ` + + The md5sum of the packages is available at: [][2] + +4. Uninstall GlusterFS v3.1 (or an earlier version) from the client + using the following command: + + `$ sudo dpkg -r glusterfs ` + + (Optional) Run `$ sudo dpkg -purge glusterfs `to purge the + configuration files. + +5. Install Gluster Native Client on the client using the following + command: + + `$ sudo dpkg -i GlusterFS_DEB_file ` + + For example: + + `$ sudo dpkg -i glusterfs-3.3.x.deb ` + +6. Ensure that TCP and UDP ports 24007 and 24008 are open on all + Gluster servers. Apart from these ports, you need to open one port + for each brick starting from port 24009. For example: if you have + five bricks, you need to have ports 24009 to 24013 open. + + You can use the following chains with iptables: + + `$ sudo iptables -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 24007:24008 -j ACCEPT ` + + `$ sudo iptables -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 24009:24014 -j ACCEPT` + + > **Note** + > + > If you already have iptable chains, make sure that the above + > ACCEPT rules precede the DROP rules. This can be achieved by + > providing a lower rule number than the DROP rule. + +### Performing a Source Installation + +To build and install Gluster Native Client from the source code + +1. Create a new directory using the following commands: + + `# mkdir glusterfs ` + + `# cd glusterfs` + +2. Download the source code. + + You can download the source at [][1]. + +3. Extract the source code using the following command: + + `# tar -xvzf SOURCE-FILE ` + +4. Run the configuration utility using the following command: + + `# ./configure ` + + `GlusterFS configure summary ` + + `================== ` + + `FUSE client : yes ` + + `Infiniband verbs : yes ` + + `epoll IO multiplex : yes ` + + `argp-standalone : no ` + + `fusermount : no ` + + `readline : yes` + + The configuration summary shows the components that will be built + with Gluster Native Client. + +5. Build the Gluster Native Client software using the following + commands: + + `# make ` + + `# make install` + +6. Verify that the correct version of Gluster Native Client is + installed, using the following command: + + `# glusterfs –-version` + +Mounting Volumes +---------------- + +After installing the Gluster Native Client, you need to mount Gluster +volumes to access data. There are two methods you can choose: + +- ? + +- ? + +After mounting a volume, you can test the mounted volume using the +procedure described in ?. + +> **Note** +> +> Server names selected during creation of Volumes should be resolvable +> in the client machine. You can use appropriate /etc/hosts entries or +> DNS server to resolve server names to IP addresses. + +### Manually Mounting Volumes + +To manually mount a Gluster volume + +- To mount a volume, use the following command: + + `# mount -t glusterfs HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR` + + For example: + + `# mount -t glusterfs server1:/test-volume /mnt/glusterfs` + + > **Note** + > + > The server specified in the mount command is only used to fetch + > the gluster configuration volfile describing the volume name. + > Subsequently, the client will communicate directly with the + > servers mentioned in the volfile (which might not even include the + > one used for mount). + > + > If you see a usage message like "Usage: mount.glusterfs", mount + > usually requires you to create a directory to be used as the mount + > point. Run "mkdir /mnt/glusterfs" before you attempt to run the + > mount command listed above. + +**Mounting Options** + +You can specify the following options when using the +`mount -t glusterfs` command. Note that you need to separate all options +with commas. + +backupvolfile-server=server-name + +volfile-max-fetch-attempts=number of attempts + +log-level=loglevel + +log-file=logfile + +transport=transport-type + +direct-io-mode=[enable|disable] + +For example: + +`# mount -t glusterfs -o backupvolfile-server=volfile_server2 --volfile-max-fetch-attempts=2 log-level=WARNING,log-file=/var/log/gluster.log server1:/test-volume /mnt/glusterfs` + +If `backupvolfile-server` option is added while mounting fuse client, +when the first volfile server fails, then the server specified in +`backupvolfile-server` option is used as volfile server to mount the +client. + +In `--volfile-max-fetch-attempts=X` option, specify the number of +attempts to fetch volume files while mounting a volume. This option is +useful when you mount a server with multiple IP addresses or when +round-robin DNS is configured for the server-name.. + +### Automatically Mounting Volumes + +You can configure your system to automatically mount the Gluster volume +each time your system starts. + +The server specified in the mount command is only used to fetch the +gluster configuration volfile describing the volume name. Subsequently, +the client will communicate directly with the servers mentioned in the +volfile (which might not even include the one used for mount). + +**To automatically mount a Gluster volume** + +- To mount a volume, edit the /etc/fstab file and add the following + line: + + `HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR glusterfs defaults,_netdev 0 0 ` + + For example: + + `server1:/test-volume /mnt/glusterfs glusterfs defaults,_netdev 0 0` + +**Mounting Options** + +You can specify the following options when updating the /etc/fstab file. +Note that you need to separate all options with commas. + +log-level=loglevel + +log-file=logfile + +transport=transport-type + +direct-io-mode=[enable|disable] + +For example: + +`HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR glusterfs defaults,_netdev,log-level=WARNING,log-file=/var/log/gluster.log 0 0 ` + +### Testing Mounted Volumes + +To test mounted volumes + +- Use the following command: + + `# mount ` + + If the gluster volume was successfully mounted, the output of the + mount command on the client will be similar to this example: + + `server1:/test-volume on /mnt/glusterfs type fuse.glusterfs (rw,allow_other,default_permissions,max_read=131072` + +- Use the following command: + + `# df` + + The output of df command on the client will display the aggregated + storage space from all the bricks in a volume similar to this + example: + + `# df -h /mnt/glusterfs Filesystem Size Used Avail Use% Mounted on server1:/test-volume 28T 22T 5.4T 82% /mnt/glusterfs` + +- Change to the directory and list the contents by entering the + following: + + `# cd MOUNTDIR ` + + `# ls` + +- For example, + + `# cd /mnt/glusterfs ` + + `# ls` + +NFS +=== + +You can use NFS v3 to access to gluster volumes. Extensive testing has +be done on GNU/Linux clients and NFS implementation in other operating +system, such as FreeBSD, and Mac OS X, as well as Windows 7 +(Professional and Up), Windows Server 2003, and others, may work with +gluster NFS server implementation. + +GlusterFS now includes network lock manager (NLM) v4. NLM enables +applications on NFSv3 clients to do record locking on files on NFS +server. It is started automatically whenever the NFS server is run. + +You must install nfs-common package on both servers and clients (only +for Debian-based) distribution. + +This section describes how to use NFS to mount Gluster volumes (both +manually and automatically) and how to verify that the volume has been +mounted successfully. + +Using NFS to Mount Volumes +-------------------------- + +You can use either of the following methods to mount Gluster volumes: + +- ? + +- ? + +**Prerequisite**: Install nfs-common package on both servers and clients +(only for Debian-based distribution), using the following command: + +`$ sudo aptitude install nfs-common ` + +After mounting a volume, you can test the mounted volume using the +procedure described in ?. + +### Manually Mounting Volumes Using NFS + +To manually mount a Gluster volume using NFS + +- To mount a volume, use the following command: + + `# mount -t nfs -o vers=3 HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR` + + For example: + + `# mount -t nfs -o vers=3 server1:/test-volume /mnt/glusterfs` + + > **Note** + > + > Gluster NFS server does not support UDP. If the NFS client you are + > using defaults to connecting using UDP, the following message + > appears: + > + > `requested NFS version or transport protocol is not supported`. + + **To connect using TCP** + +- Add the following option to the mount command: + + `-o mountproto=tcp ` + + For example: + + `# mount -o mountproto=tcp -t nfs server1:/test-volume /mnt/glusterfs` + +**To mount Gluster NFS server from a Solaris client** + +- Use the following command: + + `# mount -o proto=tcp,vers=3 nfs://HOSTNAME-OR-IPADDRESS:38467/VOLNAME MOUNTDIR` + + For example: + + ` # mount -o proto=tcp,vers=3 nfs://server1:38467/test-volume /mnt/glusterfs` + +### Automatically Mounting Volumes Using NFS + +You can configure your system to automatically mount Gluster volumes +using NFS each time the system starts. + +**To automatically mount a Gluster volume using NFS** + +- To mount a volume, edit the /etc/fstab file and add the following + line: + + `HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR nfs defaults,_netdev,vers=3 0 0` + + For example, + + `server1:/test-volume /mnt/glusterfs nfs defaults,_netdev,vers=3 0 0` + + > **Note** + > + > Gluster NFS server does not support UDP. If the NFS client you are + > using defaults to connecting using UDP, the following message + > appears: + > + > `requested NFS version or transport protocol is not supported.` + + To connect using TCP + +- Add the following entry in /etc/fstab file : + + `HOSTNAME-OR-IPADDRESS:/VOLNAME MOUNTDIR nfs defaults,_netdev,mountproto=tcp 0 0` + + For example, + + `server1:/test-volume /mnt/glusterfs nfs defaults,_netdev,mountproto=tcp 0 0` + +**To automount NFS mounts** + +Gluster supports \*nix standard method of automounting NFS mounts. +Update the /etc/auto.master and /etc/auto.misc and restart the autofs +service. After that, whenever a user or process attempts to access the +directory it will be mounted in the background. + +### Testing Volumes Mounted Using NFS + +You can confirm that Gluster directories are mounting successfully. + +**To test mounted volumes** + +- Use the mount command by entering the following: + + `# mount` + + For example, the output of the mount command on the client will + display an entry like the following: + + `server1:/test-volume on /mnt/glusterfs type nfs (rw,vers=3,addr=server1)` + +- Use the df command by entering the following: + + `# df` + + For example, the output of df command on the client will display the + aggregated storage space from all the bricks in a volume. + + # df -h /mnt/glusterfs + Filesystem Size Used Avail Use% Mounted on + server1:/test-volume 28T 22T 5.4T 82% /mnt/glusterfs + +- Change to the directory and list the contents by entering the + following: + + `# cd MOUNTDIR` + + `# ls` + + For example, + + ` + + ` + + `# ls` + +CIFS +==== + +You can use CIFS to access to volumes when using Microsoft Windows as +well as SAMBA clients. For this access method, Samba packages need to be +present on the client side. You can export glusterfs mount point as the +samba export, and then mount it using CIFS protocol. + +This section describes how to mount CIFS shares on Microsoft +Windows-based clients (both manually and automatically) and how to +verify that the volume has mounted successfully. + +> **Note** +> +> CIFS access using the Mac OS X Finder is not supported, however, you +> can use the Mac OS X command line to access Gluster volumes using +> CIFS. + +Using CIFS to Mount Volumes +--------------------------- + +You can use either of the following methods to mount Gluster volumes: + +- ? + +- ? + +After mounting a volume, you can test the mounted volume using the +procedure described in ?. + +You can also use Samba for exporting Gluster Volumes through CIFS +protocol. + +### Exporting Gluster Volumes Through Samba + +We recommend you to use Samba for exporting Gluster volumes through the +CIFS protocol. + +**To export volumes through CIFS protocol** + +1. Mount a Gluster volume. For more information on mounting volumes, + see ?. + +2. Setup Samba configuration to export the mount point of the Gluster + volume. + + For example, if a Gluster volume is mounted on /mnt/gluster, you + must edit smb.conf file to enable exporting this through CIFS. Open + smb.conf file in an editor and add the following lines for a simple + configuration: + + [glustertest] + + comment = For testing a Gluster volume exported through CIFS + + path = /mnt/glusterfs + + read only = no + + guest ok = yes + +Save the changes and start the smb service using your systems init +scripts (/etc/init.d/smb [re]start). + +> **Note** +> +> To be able mount from any server in the trusted storage pool, you must +> repeat these steps on each Gluster node. For more advanced +> configurations, see Samba documentation. + +### Manually Mounting Volumes Using CIFS + +You can manually mount Gluster volumes using CIFS on Microsoft +Windows-based client machines. + +**To manually mount a Gluster volume using CIFS** + +1. Using Windows Explorer, choose **Tools \> Map Network Drive…** from + the menu. The **Map Network Drive**window appears. + +2. Choose the drive letter using the **Drive** drop-down list. + +3. Click **Browse**, select the volume to map to the network drive, and + click **OK**. + +4. Click **Finish.** + +The network drive (mapped to the volume) appears in the Computer window. + +**Alternatively, to manually mount a Gluster volume using CIFS.** + +- Click **Start \> Run** and enter the following: + + ` + + ` + + For example: + + ` + + ` + +### Automatically Mounting Volumes Using CIFS + +You can configure your system to automatically mount Gluster volumes +using CIFS on Microsoft Windows-based clients each time the system +starts. + +**To automatically mount a Gluster volume using CIFS** + +The network drive (mapped to the volume) appears in the Computer window +and is reconnected each time the system starts. + +1. Using Windows Explorer, choose **Tools \> Map Network Drive…** from + the menu. The **Map Network Drive**window appears. + +2. Choose the drive letter using the **Drive** drop-down list. + +3. Click **Browse**, select the volume to map to the network drive, and + click **OK**. + +4. Click the **Reconnect** at logon checkbox. + +5. Click **Finish.** + +### Testing Volumes Mounted Using CIFS + +You can confirm that Gluster directories are mounting successfully by +navigating to the directory using Windows Explorer. + + []: http://bits.gluster.com/gluster/glusterfs/3.3.0qa30/x86_64/ + [1]: http://www.gluster.org/download/ + [2]: http://download.gluster.com/pub/gluster/glusterfs |