iSCSI on TrueNAS: Complete Configuration and Management Guide

Introduction

iSCSI (Internet Small Computer System Interface) is a protocol that allows remote access to storage blocks over a standard IP network. In the context of IT infrastructure, especially in virtualization environments such as Proxmox and VMware, iSCSI offers an efficient and scalable solution for storage presentation.

TrueNAS, an open-source platform based on FreeBSD and ZFS, is an excellent choice for implementing an enterprise iSCSI server. In this article, we explore how to configure and manage iSCSI connections robustly and securely.

What is iSCSI and Why Use It?

Basic Operation

iSCSI encapsulates SCSI (Small Computer System Interface) commands in TCP/IP packets, allowing:

• Remote servers access storage as if it were connected locally

• Multiple initiators (clients) connect to a single target

• Standard networks are used for storage traffic (unlike Fibre Channel)

Advantages for B2B Infrastructure

Architecture: iSCSI Client-Server

┌─────────────────────────────────────────────┐
│        Rede IP (Ethernet)                   │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐      ┌──────────────┐   │
│  │ Initiator 1  │      │ Initiator 2  │   │
│  │ (Proxmox)    │◄────►│ (Linux Host) │   │
│  └──────────────┘      └──────────────┘   │
│         │                     │             │
│         └─────────┬───────────┘             │
│                   │ (iSCSI Protocol)       │
│                   ▼                        │
│         ┌──────────────────┐              │
│         │   Target Portal  │              │
│         │  (TrueNAS 0.95)  │              │
│         │  - Portal Group  │              │
│         │  - Target Name   │              │
│         │  - LUN (extent)  │              │
│         └──────────────────┘              │
│                   │                       │
│         ┌─────────▼──────────┐           │
│         │   ZFS Dataset      │           │
│         │   Storage Pool     │           │
│         └────────────────────┘           │
└─────────────────────────────────────────────┘

Step by Step: Configuring iSCSI on TrueNAS

Prerequisites

• TrueNAS installed and accessible via network (e.g., 192.168.0.95)

• Storage pool already created with available space

• Dedicated network for iSCSI (recommended) or segregated VLAN

• Initiators (Proxmox, hypervisors, Linux servers) with IP connectivity

1. Create a Dataset for iSCSI

First, prepare the storage space:

1. Go to Storage → Datasets

2. Select your pool (e.g., vol-bkp)

3. Click Add Dataset

4. Configure:

   • Name: iscsi-lun-01

   • Recordsize: 16K (default for OLTP/DB) or 128K (for random workloads)

   • Compression: lz4 (balanced between performance and compression rate)

   • Sync: Disabled (for better throughput) or Standard (safer)

Note: For critical environments (Oracle, SQL Server), use Sync: Standard and consider ZFS Intent Log (ZIL) on SSD.

2. Configure Extent (LUN Export)

An Extent is the equivalent of a virtual disk that will be exported via iSCSI:

1. Go to Shares → iSCSI → Extents

2. Click Add

3. Configure:

   • Type: Device (physical disk) or File (file on dataset)

   • For File-based Extent:

     • Dataset: Select vol-bkp/iscsi-lun-01

     • Logical Block Size: 4096 (modern default)

     • Size: Defines LUN size (e.g., 500 GB)

Recomendações por caso de uso:
- Oracle/SQL: Logical Block Size 4096, Sync padrão, +40% overhead no tamanho
- Proxmox VM storage: 4096, Compression LZ4, throughput oriented
- Backup/Archive: 8192, Compression máxima

3. Create Target (iSCSI Target)

The Target is the access point that initiators will contact:

1. Go to Shares → iSCSI → Targets

2. Click Add

3. Configure:

   • Target Name: iqn.2026-08.br.nyverra:storage.vol-bkp

     • IQN format: iqn.yyyy-mm.reverse-domain:unique-identifier

   • Target Alias: Nyverra-Storage-Backup

   • Select Groups: Next tab

Important: Use a unique and standardized IQN. Example for your company:

iqn.2026-08.br.nyverra:storage.prod.oracle
iqn.2026-08.br.nyverra:storage.proxmox
iqn.2026-08.br.nyverra:backup.cliente-xyz

4. Map Extent to Target (LUN Mapping)

1. On the Target to LUN Mapping tab, click Add

2. Configure:

   • Logical Unit Number (LUN): 0 (first LUN of the target)

   • Extent: Select iscsi-lun-01 (created earlier)

Multiple extents? Use LUN 0, 1, 2... for each extent mapped to the same target.

5. Configure Portal Group

A Portal Group defines listening IPs and ports:

1. Go to Shares → iSCSI → Portals

2. Check if default exists:

   • IP: 0.0.0.0 (listens on all interfaces)

   • Port: 3260 (iSCSI default)

For production security, create a specific portal:

1. Click Add

2. Configure:

   • IP Address: 192.168.0.95 (your storage network)

   • Port: 3260

   • Comment: Production iSCSI Network

6. Configure Authorized Access (ACL)

Restrict access to specific initiators:

1. Go to Shares → iSCSI → Authorized Access

2. Click Add

3. Configure:

   • Initiator Group: Select (or create new)

   • Initiator IQN: Specify the client IQN

     • Example: iqn.1991-05.com.example:storage.prod01 (Proxmox node)

Tip: Leave empty for "Allow all initiators" (only if trusted or in lab)

7. Enable the iSCSI Service

1. Go to Services

2. Locate iSCSI

3. Toggle to ON

4. Optionally, check Start Automatically

Connect an Initiator (Proxmox Example)

On your Proxmox node, configure access to the LUN:

Via CLI (Proxmox PVE)

# Instalar cliente iSCSI
apt-get install open-iscsi -y

# Descobrir targets disponíveis
iscsiadm -m discovery -t sendtargets -p 192.168.0.95

# Saída esperada:
# 192.168.0.95:3260,1 iqn.2026-08.br.nyverra:storage.vol-bkp

# Conectar ao target
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.vol-bkp -p 192.168.0.95 -l

# Verificar conexão
iscsiadm -m session -o show

# Listar blocos iSCSI
lsblk | grep sd
# Exemplo: sdb (LUN mapeada)

Via Proxmox Web UI

1. Datacenter → Storage

2. Add → ISCSI

3. Configure:

   • ID: nyverra-backup

   • Target: 192.168.0.95

   • Target Portal: 192.168.0.95:3260

   • Target: iqn.2026-08.br.nyverra:storage.vol-bkp

   • LUN: 0

   • Content: Check Disk image, VZDump backup file, as needed

4. Verify → Proxmox will automatically detect the LUN size

Connect an Oracle Linux 7.9 Server

For Oracle Linux Server 7.9 (RHEL 7.9 compatible) servers, such as srvoracle-prod, the configuration is similar but with systemd and yum specifics:

Prerequisites on Oracle Linux 7.9

# Verificar versão
cat /etc/oracle-release
# Oracle Linux Server release 7.9

# Atualizar sistema
yum update -y

# Desativar firewalld (se necessário) ou configurar regras
systemctl status firewalld
# Se ativo: systemctl stop firewalld && systemctl disable firewalld

1. Install iSCSI Client

# Instalar open-iscsi (iscsi-initiator-utils em RHEL/OL)
yum install -y iscsi-initiator-utils

# Verificar instalação
rpm -qa | grep iscsi
# iscsi-initiator-utils-6.2.1.3-16.el7.x86_64

# Verificar versão
iscsiadm --version
# iscsiadm version 6.2.1.3

2. Configure Initiator IQN

The IQN (iSCSI Qualified Name) identifies your server to the target:

# Verificar IQN atual
cat /etc/iscsi/initiatorname.iscsi
# InitiatorName=iqn.1993-08.org.linux-xxx:xxxxx

# Customizar para seu servidor Oracle
vi /etc/iscsi/initiatorname.iscsi

# Alterar para:
# InitiatorName=iqn.2026-08.br.nyverra:initiator.srvoracle-prod

Important: Use a unique IQN per server. We recommend including the hostname:

iqn.2026-08.br.nyverra:initiator.srvoracle-prod
iqn.2026-08.br.nyverra:initiator.srvoracle-backup

3. Start the iscsid Service

# Iniciar daemon iSCSI
systemctl start iscsid

# Ativar na inicialização (importante para produção)
systemctl enable iscsid

# Verificar status
systemctl status iscsid
# ● iscsid.service - Open-iSCSI daemon
#    Loaded: loaded (/usr/lib/systemd/system/iscsid.service; enabled)
#    Active: active (running)

4. Discover Targets on TrueNAS

# Descobrir targets disponíveis no TrueNAS (192.168.0.95)
iscsiadm -m discovery -t sendtargets -p 192.168.0.95

# Saída esperada:
# 192.168.0.95:3260,1 iqn.2026-08.br.nyverra:storage.vol-bkp
# 192.168.0.95:3260,1 iqn.2026-08.br.nyverra:storage.oracle

5. Connect to the iSCSI Target

# Conectar (login) ao target
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.oracle -p 192.168.0.95 -l

# Saída esperada:
# Logging in to [iface: default, target: iqn.2026-08.br.nyverra:storage.oracle, portal: 192.168.0.95,3260] (multiple)
# Login successful.

# Verificar todas as sessões iSCSI ativas
iscsiadm -m session -o show

# Saída:
# tcp: [1] 192.168.0.95:3260,1 iqn.2026-08.br.nyverra:storage.oracle (non-flash)

6. Verify Disk Blocks

# Listar blocos iSCSI mapeados
lsblk -i

# Exemplo de saída:
# NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
# sda           8:0    0  200G  0 disk 
# ├─sda1        8:1    0  500M  0 part /boot
# └─sda2        8:2    0 199.5G  0 part /
# sdb           8:16   0  2.7T  0 disk   <- iSCSI LUN
# sdc           8:32   0  1.5T  0 disk   <- Outra LUN

# Informações detalhadas iSCSI
lsscsi -i

# Exemplo:
# [2:0:0:0]    disk    SLIO-ORG vol-bkp           4001  /dev/sdb
# [3:0:0:0]    disk    SLIO-ORG storage-oracle    4001  /dev/sdc

7. Connection Persistence at Boot

To ensure LUNs are mounted automatically at boot:

# Editar configuração de nó iSCSI
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.oracle -p 192.168.0.95 -o update -n node.startup -v automatic

# Verificar configuração
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.oracle -p 192.168.0.95 -o show

# Saída esperada:
# node.startup = automatic
# node.leading_login = No
# ...

8. Format and Mount LUN (Optional)

If you need to format the LUN for Oracle use:

# Listar discos
fdisk -l | grep sdb
# Disk /dev/sdb: 2748.9 GB, 2748901658624 bytes

# Criar partição (se necessário)
parted /dev/sdb mklabel gpt
parted /dev/sdb mkpart primary 0% 100%
parted /dev/sdb print

# Formatar (EXT4 para Oracle datafiles - NÃO recomendado)
# OU deixar como bloco raw (recomendado para Oracle):
# mkfs.ext4 -L iscsi-oracle /dev/sdb1

# Montar (opcional)
mkdir -p /mnt/iscsi-oracle
mount /dev/sdb1 /mnt/iscsi-oracle

# Persistir em /etc/fstab
# /dev/sdb1  /mnt/iscsi-oracle  ext4  defaults,_netdev  0 2

Note for Oracle: Use raw device (without ext4 formatting) for better performance. iSCSI LUNs should be managed via ASM or LVM, not systemd mount.

9. Complete Oracle Linux 7.9 Setup Script

#!/bin/bash
# Script: configurar-iscsi-oracle.sh

set -e

TRUENAS_IP="192.168.0.95"
TARGET_NAME="iqn.2026-08.br.nyverra:storage.oracle"
INITIATOR_NAME="iqn.2026-08.br.nyverra:initiator.srvoracle-prod"

echo "[*] Atualizando sistema..."
yum update -y

echo "[*] Instalando open-iscsi..."
yum install -y iscsi-initiator-utils device-mapper-multipath

echo "[*] Configurando IQN do iniciador..."
sed -i "s/^InitiatorName=.*/InitiatorName=$INITIATOR_NAME/" /etc/iscsi/initiatorname.iscsi

echo "[*] Iniciando serviço iscsid..."
systemctl start iscsid
systemctl enable iscsid

echo "[*] Descobrindo targets em $TRUENAS_IP..."
iscsiadm -m discovery -t sendtargets -p $TRUENAS_IP

echo "[*] Conectando ao target $TARGET_NAME..."
iscsiadm -m node -T $TARGET_NAME -p $TRUENAS_IP -l

echo "[*] Configurando persistência (auto-login)..."
iscsiadm -m node -T $TARGET_NAME -p $TRUENAS_IP -o update -n node.startup -v automatic

echo "[*] Aguardando LUN aparecer..."
sleep 5

echo "[*] Blocos mapeados:"
lsblk -i | grep -E "sdb|sdc|sdd"

echo "[*] Sessões iSCSI:"
iscsiadm -m session -o show

echo "[SUCCESS] iSCSI configurado com sucesso em Oracle Linux 7.9!"

Using the script:

chmod +x configurar-iscsi-oracle.sh
sudo ./configurar-iscsi-oracle.sh

Tuning for Oracle on Linux 7.9

To optimize iSCSI in Oracle environments:

# Aumentar filas de IO
echo "options iscsi_tcp rcv_nnt=512" | tee -a /etc/modprobe.d/iscsi.conf
modprobe -r iscsi_tcp
modprobe iscsi_tcp

# Aumentar TCP buffers para melhor throughput
sysctl -w net.core.rmem_max=134217728
sysctl -w net.core.wmem_max=134217728
sysctl -w net.ipv4.tcp_rmem="4096 87380 67108864"
sysctl -w net.ipv4.tcp_wmem="4096 65536 67108864"

# Persistir em /etc/sysctl.conf
cat >> /etc/sysctl.conf <

# Instalar device-mapper-multipath
yum install -y device-mapper-multipath

# Iniciar serviço
systemctl start multipathd
systemctl enable multipathd

# Gerar configuração padrão
mpathconf --enable --with_multipathd y

# Verificar multipaths
multipath -ll

# Exemplo de saída:
# 360001405b4c7c9844e7451d942ce4b33 dm-0 SLIO-ORG,vol-bkp
# size=2.7T features='0' hwhandler='1 alua' wp=rw
# `-+- policy='service-time 0' prio=50 status=enabled
#   `- 2:0:0:0 sdb 8:16 active ready running

# Listar todas as sessões descobertas
iscsiadm -m node

# Deletar uma conexão (logout)
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.oracle -p 192.168.0.95 -u

# Reconectar
iscsiadm -m node -T iqn.2026-08.br.nyverra:storage.oracle -p 192.168.0.95 -l

# Logout de todos os targets
iscsiadm -m session -u all

# Relogin em todos os targets configurados
iscsiadm -m node -l all

# Verificar status
systemctl status iscsid

# Se parado, iniciar
systemctl start iscsid
systemctl enable iscsid

# Checar logs
journalctl -u iscsid -n 50

# Redescobrir targets
iscsiadm -m discovery -t sendtargets -p 192.168.0.95 --op update

# Verificar conectividade network
ping -c 5 192.168.0.95
ss -tunap | grep 3260

# Aumentar verbosidade
iscsiadm -m session -o show -P 3

# Verificar firewall
firewall-cmd --list-all
firewall-cmd --add-port=3260/tcp --permanent
firewall-cmd --reload

# Logs do kernel
dmesg | tail -50 | grep -i iscsi

# Forçar descoberta de blocos
iscsiadm -m node -l all

# Verificar se node.startup = automatic
iscsiadm -m node -o show | grep startup

# Se não estiver, ativar:
iscsiadm -m node -T  -p  -o update -n node.startup -v automatic

# Rebootar e testar
reboot

# Monitorar latência
ping -i 0.2 -c 1000 192.168.0.95 | tail -3

# Verificar jitter (variação)
# Expected: < 5ms em rede local

# Se latência alta, verificar:
# 1. Rede dedicada vs compartilhada
# 2. MTU frames (usar jumbo frames 9000 se possível)
# 3. VLAN tagging

# Aumentar timeout de reconexão
iscsiadm -m node -T  -p  -o update \
  -n node.conn[0].timeo.replacement_timeout -v 120

# Após conectar LUN, criar disco ASM
# (Executar como oracle user ou via asmcmd)

asmcmd
# ASMCMD> create diskgroup dg_iscsi_data external redundancy disk='/dev/sdb' quorumfail=proactive;
# Diskgroup created.

# Verificar discos
# ASMCMD> lsdsk -G dg_iscsi_data;

# No Proxmox/Linux, criar multipath
apt-get install multipath-tools -y

# Configurar /etc/multipath.conf para round-robin
multipath -ll

- ZFS recordsize: 16K (banco de dados), 128K (seqüencial)
- Compression: LZ4 (padrão)
- Sync: Standard (para dados críticos)
- Cache: Arc (ajuste em System → Tuning)

# Aumentar queue depth para melhor throughput
echo "options iscsi_tcp rcv_nnt=512" >> /etc/modprobe.d/iscsi.conf

# Verificar sesões iSCSI
iscsiadm -m session -o show

# UFW (Ubuntu/Proxmox)
ufw allow from 192.168.0.0/24 to any port 3260

# iptables (Proxmox/PVE)
iptables -A INPUT -p tcp --dport 3260 -s 192.168.0.0/24 -j ACCEPT

# Redescobrir targets
iscsiadm -m discovery -t sendtargets -p 192.168.0.95 --op update

# Verificar firewall TrueNAS
# Settings → Advanced → Sysctl → net.inet.ip.fw.verbose=1

TrueNAS 192.168.0.95
├── Pool: vol-oracle (RAID-Z2, ZFS)
├── Dataset: iscsi-data
│   └── LUN (2 TB) → Proxmox node 1
├── Dataset: iscsi-archive
│   └── LUN (1 TB) → Proxmox node 2
└── Dataset: iscsi-redo
    └── LUN (500 GB) → Ambos nodes (MPIO)