Skip to content

[WIP]DOCTEAM-2086: structure of iscsi article #638

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Amrita42 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

[WIP]DOCTEAM-2086: structure of iscsi article #638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cd4e91e
structure of article
Amrita42 Feb 11, 2026
44ad60d
validate
Amrita42 Feb 11, 2026
ca1792e
validate
Amrita42 Feb 11, 2026
5659b90
adds structure
Amrita42 Feb 12, 2026
0139cac
adds topics
Amrita42 Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions DC-SLES-ISCSI
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# This file originates from the project https://github.com/openSUSE/doc-kit
# This file can be edited downstream.

## Basics
MAIN="iscsi.asm.xml"
SRC_DIR="articles"
IMG_SRC_DIR="images"

## Profiling
PROFOS="sles"
PROFCONDITION="16.0"
#STRUCTID="sles-iscsi"
#PROFARCH="x86_64;zseries;power;aarch64"

DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"

## stylesheet location
STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2021-ns"
146 changes: 146 additions & 0 deletions articles/iscsi.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
type="application/relax-ng-compact-syntax"?>
<!DOCTYPE assembly
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<assembly version="5.2" xml:lang="en"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns="http://docbook.org/ns/docbook">
<!-- R E S O U R C E S -->
<resources>
<resource xml:id="_about-iscsi" href="../concepts/intro-iscsi.xml"/>
<resource xml:id="_install-iscsi" href="../concepts/install-iscsi.xml"/>
<resource xml:id="_troubleshoot-iscsi" href="../tasks/configure-iscsi-target.xml"/>
<resource xml:id="_troubleshoot-iscsi" href="../tasks/troubleshooting-iscsi.xml"/>
<resource xml:id="_troubleshoot-iscsi" href="../tasks/configure-iscsi-initiator.xml"/>
<resource xml:id="_more-info-iscsi" href="../glues/info-iscsi.xml"/>
<resource href="../common/legal.xml" xml:id="_legal"/>
<resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl"/>
</resources>
<!-- S T R U C T U R E -->
<structure renderas="article" xml:id="iscsi" xml:lang="en">
<merge>
<title>Understanding iSCSI</title>
<revhistory xml:id="rh-iscsi">
<revision><date>2026-02-11</date>
<revdescription>
<para>
Initial version
</para>
</revdescription>
</revision>
</revhistory>

<!-- Maintainer-->
<meta name="maintainer" content="amrita.sathivel@suse.com" its:translate="no"/>

<!-- Series-->
<meta name="series" its:translate="no">Smart Docs</meta>

<!-- Task -->
<meta name="task" its:translate="no">
<phrase>Administration</phrase>
<phrase>Configuration</phrase>
<phrase>Security</phrase>
</meta>

<!-- Docmanager -->
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Documentation</dm:component>
<dm:product>SUSE Linux Enterprise Server 16.0</dm:product>
<dm:assignee>amrita.sakthivel@suse.com</dm:assignee>
</dm:bugtracker>
<dm:translation>yes</dm:translation>
</dm:docmanager>

<!-- Architecture -->
<meta name="architecture" its:translate="no">
<phrase>&x86-64;</phrase>
<phrase>&power;</phrase>
<phrase>&zseries;</phrase>
<phrase>&aarch64;</phrase>
</meta>

<!-- Productname & Version -->
<meta name="productname" its:translate="no">
<productname version="16.0" os="sles">&productname;</productname>
</meta>

<!-- Social Media -->
<meta name="title" its:translate="yes">Introduction to iSCSI</meta>
<meta name="social-descr" its:translate="yes">Understanding iSCSI allows you to treat remote network storage as a locally attached hard drive, giving you the power to run high-performance applications like databases and virtual machines</meta>

<!-- Search -->
<meta name="description" its:translate="yes">Use iSCSI to manage your storage</meta>

<abstract>
<variablelist>
<varlistentry>
<term>WHAT?</term>
<listitem>
<para>
iSCSI is a networking standard that allows a system to treat a remote storage device over an Ethernet network as if it were a physically plugged-in local hard drive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WHY?</term>
<listitem>
<para>
Learn how to use iSCSI is used to provide a cost-effective way to consolidate storage into a central location while allowing remote servers to access that data with the high performance and formatting flexibility of a locally attached hard drive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EFFORT</term>
<listitem>
<para>
The average reading time of this article is approximately 40 minutes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REQUIREMENTS</term>
<listitem>
<itemizedlist>
<listitem>
<para>
<emphasis>Linux fundamentals:</emphasis> Understanding basic Linux commands, file permissions, directory structures
and use of the command line.
</para>
</listitem>
<listitem>
<para>
<emphasis>Networking fundamentals:</emphasis> Understanding how IP addresses and subnets work, as iSCSI relies on your local network to find the storage. It also helps to know that iSCSI uses TCP Port 3260 to communicate.
</para>
</listitem>
<listitem>
<para>
<emphasis>Storage fundamentals:</emphasis> Understanding the difference between file level storage (like a folder on Google Drive) and block level storage (like a raw, unformatted hard drive), as iSCSI is strictly block-level.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</abstract>
</merge>
<module resourceref="_about-iscsi" renderas="section"/>
<module resourceref="_install-iscsi" renderas="section"/>
<module resourceref="_configure-iscsi-initiator" renderas="section"/>
<module resourceref="_configure-iscsi-target" renderas="section"/>
<module resourceref="_troubleshoot-iscsi" renderas="section"/>
<module resourceref="_more-info-iscsi" renderas="section"/>
<module resourceref="_legal"/>
<module resourceref="_gfdl">
<output renderas="appendix"/>
</module>
</structure>
</assembly>
30 changes: 30 additions & 0 deletions concepts/install-iscsi.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="install-iscsi"
role="concept" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Installing the iSCSI LIO target server and iSCSI initiator</title>
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<abstract>
<para>

</para>
</abstract>
</info>
<para>
</para>

</topic>
72 changes: 72 additions & 0 deletions concepts/intro-iscsi.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="about-iscsi"
role="concept" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>About iSCSI</title>
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<abstract>
<para>
iSCSI (Internet Small Computer Systems Interface) is a networking protocol that enables the transmission of SCSI commands over IP networks, allowing a system to access remote storage as if it were a locally attached hard drive.
</para>
</abstract>
</info>
<para>
By wrapping storage-level data blocks into standard TCP/IP packets, it bridges the gap between local storage performance and network flexibility, using existing Ethernet infrastructure like switches and cables rather than expensive, specialized hardware. In an iSCSI setup, the initiator connects to a target to claim a portion of disk space known as a LUN (Logical Unit Number), which the client can then format and manage with its own native file system.
Linux iSCSI provides iSCSI initiator and iSCSI LIO target software for connecting Linux servers to central storage systems.
</para>
<para>In a physical iSCSI environment, the initiator is the server’s hardware that requests data, the LIO target is the physical storage appliance that hosts the data and the LUN (Logical Unit Number) represents the specific physical disk capacity assigned to the server.</para>
<itemizedlist>
<listitem><para><emphasis role="bold">The iSCSI Initiator:</emphasis>The initiator is the physical server that needs to consume the storage. It initiates the conversation with the target.</para>
<itemizedlist>
<listitem><para><emphasis role="bold">HBA (Host Bus Adapter):</emphasis> While you can use a standard network card, a physical iSCSI HBA is a dedicated expansion card installed in the server's PCIe slot. It contains its own processor to handle storage traffic and prevents the server’s main CPU from becoming overwhelmed.</para></listitem>
<listitem><para><emphasis role="bold">Physical Ports:</emphasis> These are the dedicated connection points on the server used exclusively for storage traffic to ensure low latency and high throughput.</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="bold">The iSCSI LIO Target:</emphasis>The target is the physical hardware device that houses the data. LIO (Linux-IO) is the standard, open-source storage enterprise-grade target for the Linux kernel.</para>
<itemizedlist>
<listitem><para><emphasis role="bold">Chassis and Controllers:</emphasis> The physical box contains one or more controllers (specialized systems) that manage the data flow.</para></listitem>
<listitem><para><emphasis role="bold">Drive Backplane:</emphasis> This is the physical internal wiring that connects the storage controllers to the actual rows of hard drives or SSDs.</para></listitem>
<listitem><para><emphasis role="bold">Network Ports:</emphasis> The physical Ethernet ports (RJ45 for copper or SFP+ for fiber) that plug into the storage network switch.</para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="bold">The LUN:</emphasis> While a LUN is a logical identifier, it directly corresponds to the physical disk resources allocated to a server.</para>
<itemizedlist>
<listitem><para><emphasis role="bold">Physical Disk Groups:</emphasis> A LUN is often a physical collection of disks bound together in a RAID configuration.</para></listitem>
<listitem><para><emphasis role="bold">The Drive to the OS:</emphasis> From the server's perspective, the LUN is treated as a physical local hard drive. You can format, partition and install files on it just like a drive plugged directly into the motherboard.</para></listitem>
<listitem><para><emphasis role="bold">Physical Capacity:</emphasis> The size of the LUN is limited by the number of physical disks installed in the target array.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<section xml:id="features-iscsi">
<title>Key characteristics of remote iSCSI storage</title>
<para>Following are some the common characteristics of iSCSI:</para>
<itemizedlist>
<listitem><para><emphasis role="bold">Block-Level Access:</emphasis> Unlike a network share where you see files, with iSCSI, your system sees raw sectors. This allows you to format the remote drive with any file system such as NTFS, ReFS, or ext4.</para></listitem>
<listitem><para><emphasis role="bold">Distance and Flexibility:</emphasis> The storage can be in a server rack across the room or in a data center across the city. As long as there is a network connection, the system treats it as local storage.</para></listitem>
<listitem><para><emphasis role="bold">Low Latency Requirement:</emphasis> Because the OS thinks the drive is local, it expects fast responses. This is why remote iSCSI usually requires a high-speed network ( preferably 10Gbps or higher).</para></listitem>
</itemizedlist>
</section>
<section xml:id="usecase-iscsi">
<title>Use cases for remote iSCSI storage</title>
<para>The common use cases for iSCSI include:</para>
<itemizedlist>
<listitem><para><emphasis role="bold">Virtualization:</emphasis> Servers running VMware or Hyper-V store virtual machines on remote iSCSI targets so that if one physical server dies, another can immediately take over the disk over the network.</para></listitem>
<listitem><para><emphasis role="bold">Database Hosting:</emphasis> High-performance databases like SQL Server or Oracle require block-level access to manage data placement and logging. Since iSCSI presents itself as a local physical disk rather than a shared folder, it satisfies the strict technical requirements of database software while keeping the data on a secure and centralized server.</para></listitem>
<listitem><para><emphasis role="bold">Consolidated Backup and Disaster Recovery:</emphasis> iSCSI allows organizations to centralize backups from various machines onto one large and manageable storage array. It also supports diskless booting, where a server with no internal hard drive can load its entire operating system directly from a remote iSCSI target, making hardware replacement much faster.</para></listitem>
</itemizedlist>
</section>
</topic>
24 changes: 24 additions & 0 deletions glues/info-iscsi.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<topic xml:id="more-info-iscsi"
role="glue" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>For more information</title><!-- can be changed via merge in the
assembly -->
<!--add author's e-mail address-->
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<!-- add an abstract/para here, if you need one -->
<!-- can be changed via merge in the assembly -->
</info>
<para>
</para>
</topic>
30 changes: 30 additions & 0 deletions tasks/configure-iscsi-initiator.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="configure-iscsi-initiator"
role="task" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Configuring an iSCSI initiator</title>
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<abstract>
<para>

</para>
</abstract>
</info>
<para>
</para>

</topic>
30 changes: 30 additions & 0 deletions tasks/configure-iscsi-target.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="configure-iscsi-target"
role="task" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Configuring an iSCSI target</title>
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<abstract>
<para>

</para>
</abstract>
</info>
<para>
</para>

</topic>
30 changes: 30 additions & 0 deletions tasks/troubleshooting-iscsi.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="troubleshoot-iscsi"
role="task" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Troubleshooting iSCSI</title>
<meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
<abstract>
<para>

</para>
</abstract>
</info>
<para>
</para>

</topic>