Skip to content

Commit d5818de

Browse files
devblackopsdevblackops
authored
Merge pull request #79 from dbroeglin/feature/readme-documentation
Added examples and explanations to README.md
2 parents b00bedd + 5580b7c commit d5818de

File tree

1 file changed

+133
-10
lines changed

1 file changed

+133
-10
lines changed

‎README.md‎

Lines changed: 133 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,142 @@
11
[![Build status](https://ci.appveyor.com/api/projects/status/a6oio0l6g27nhg0w?svg=true)](https://ci.appveyor.com/project/devblackops/netscaler)
22

33
# NetScaler
4-
PowerShell module for interacting with Citrix NetScaler via the Nitro API
4+
5+
PowerShell module for interacting with Citrix NetScaler via the Nitro API.
6+
7+
This module contains functions that abstract away the nitty-gritty aspects of
8+
the Nitro API. It provides a set of idiomatic PowerShell functions with
9+
parameter validation and inline documentation. The module can be used for both
10+
a better command line experience and writing scripts that automate NetScaler
11+
setup.
512

613
# Getting started
714

8-
This script establishes a session with the Netscaler instance and sets its hostname:
15+
## Login into NetScaler
16+
17+
This script establishes a session with the NetScaler instance and sets its host name:
18+
19+
```powershell
20+
$Nsip, $Username, $Password = "1.2.3.4", "nsroot", "nsroot"
21+
22+
$SecurePassword = ConvertTo-SecureString $Password -AsPlainText -Force
23+
$Credential = New-Object System.Management.Automation.PSCredential ($Username, $SecurePassword)
24+
25+
$Session = Connect-Netscaler -Hostname $Nsip -Credential $Credential -PassThru
26+
27+
Set-NSHostname -Hostname ns01 -Force -Session $Session
28+
```
29+
30+
## Initial setup
31+
32+
Once logged into a freshly installed NetScaler, the following script sets up the time zone,
33+
installs a license, saves the configuration and reboots:
34+
35+
```powershell
36+
Set-NSTimeZone -TimeZone 'GMT+01:00-CET-Europe/Zurich' -Session $Session -Force
37+
38+
Install-NSLicense -Path licenses/license.lic -Session $Session
39+
Restart-NetScaler -WarmReboot -Wait -SaveConfig -Session $Session -Force
40+
```
41+
42+
After reboot, a reconnection is required:
43+
44+
```powershell
45+
$Session = Connect-Netscaler -Hostname $Nsip -Credential $Credential -PassThru
46+
```
47+
48+
## Basic tasks
49+
50+
Once initial setup is done, regular configuration can start. The following commands
51+
will set up a VIP and SNIP:
52+
53+
```powershell
54+
Add-NSIPResource -Type SNIP -IPAddress 172.16.124.11 -SubNetMask '255.255.255.0' -VServer -Session $Session
55+
56+
Add-NSIPResource -Type VIP -IPAddress 172.16.124.12 -SubNetMask '255.255.255.0' -VServer -Session $Session
57+
```
58+
59+
This will add a DNS server:
960

1061
```powershell
11-
$Nsip, $Username, $Password = "1.2.3.4", "nsroot", "nsroot"
12-
13-
$SecurePassword = ConvertTo-SecureString $Password -AsPlainText -Force
14-
$Credential = New-Object System.Management.Automation.PSCredential ($Username, $SecurePassword)
62+
Add-NSDnsNameServer -IPAddress 1.2.3.10
63+
```
64+
65+
The line below will enable the following features:
66+
- Authentication, Authorization and Auditing,
67+
- Load balancing,
68+
- Rewrite,
69+
- SSL offloading.
70+
71+
```powershell
72+
Enable-NSFeature -Session $Session -Force -Name "aaa", "lb", "rewrite", "ssl"
73+
```
74+
75+
## Setting up a reverse proxy
76+
77+
The above example deal with setting up the stage. However, to configure NetScaler for some
78+
real work, more complex set of commands is needed. Usually, this kind of work can be abstracted
79+
in a PowerShell function. For instance, the following function will create a very simple reverse proxy:
80+
81+
```powershell
82+
New-ReverseProxy -IPAddress 172.16.124.12 -ExternalFQDN www.extlab.local -InternalFQDN www.lab.local
83+
```
84+
85+
The actual implementation could be:
86+
```powershell
87+
function New-ReverseProxy {
88+
Param(
89+
[String]$IPAddress,
90+
[String]$ExternalFQDN,
91+
[String]$InternalFQDN,
92+
[String]$CertificateName = $ExternalFQDN
93+
)
94+
$VServerName = "vsrv-$ExternalFQDN"
95+
$ServerName = "srv-$InternalFQDN"
96+
97+
New-NSLBServer -Name $ServerName -Domain $InternalFQDN
98+
Enable-NSLBServer -Name $ServerName -Force
99+
New-NSLBServiceGroup -Name svg-$ExternalFQDN -Protocol HTTP
100+
New-NSLBServiceGroupMember -Name svg-$ExternalFQDN -ServerName $ServerName
101+
102+
New-NSLBVirtualServer -Name $VServerName -IPAddress $IPAddress -ServiceType SSL -Port 443
103+
Add-NSLBVirtualServerBinding -VirtualServerName $VServerName -ServiceGroupName svg-$ExternalFQDN
104+
Enable-NSLBVirtualServer -Name $VServerName -Force
105+
106+
Add-NSLBSSLVirtualServerCertificateBinding -Certificate $CertificateName -VirtualServerName $VServerName
107+
108+
New-NSRewriteAction -Name "act-proxy-host-$InternalFQDN" -Type Replace -Target 'HTTP.REQ.HOSTNAME' -Expression "`"$InternalFQDN`""
109+
New-NSRewritePolicy -Name "pol-proxy-host-$InternalFQDN" -ActionName "act-proxy-host-$InternalFQDN" -Rule "true"
110+
Add-NSLBVirtualServerRewritePolicyBinding -VirtualServerName $VServerName -PolicyName "pol-proxy-host-$InternalFQDN" `
111+
-BindPoint Request -Priority 100
112+
}
113+
```
114+
115+
## Beyond the module
116+
117+
Although, the module is still a work in progress, there are already more than 140 functions
118+
implemented. Those functions cover most needs. However, you might occasionally need a Nitro
119+
resource that is not implemented. In that case you can rely on a simple call to `Invoke-Nitro`.
120+
For instance, the following call will set the `nsroot` user's session expiration time to 1 day
121+
(not recommended in production but very helpful in a development environment!):
122+
123+
```powershell
124+
Invoke-Nitro -Type systemuser -Method PUT -Payload @{
125+
username = "nsroot"
126+
timeout = "86400"
127+
logging = "ENABLED"
128+
externalauth = "ENABLED"
129+
} -Action Add -Force
130+
```
131+
132+
## Examples
133+
134+
For a more complete example you can take a look ad [NSConfig.ps1](https://github.com/dbroeglin/windows-lab/blob/master/NSConfig.ps1)
135+
136+
# Similar work
137+
138+
- Carl Stalhood created [a script that configures NetScaler through Nitro](http://www.carlstalhood.com/netscaler-scripting).
139+
- Santiago Cardenas wrote a series of posts about [setting up NetScaler for StoreFront](https://www.citrix.com/blogs/2014/09/19/scripting-automating-netscaler-configurations-using-nitro-rest-api-and-powershell-part-1/) with load balancing and high-availability.
140+
- Esther Barthel has done a few [talks](https://www.citrix.com/blogs/2016/04/29/automate-netscaler-using-nitro-api-and-powershell/) about automating NetScaler configuration through Nitro.
141+
15142

16-
$Session = Connect-Netscaler -Hostname $Nsip -Credential $Credential -PassThru
17-
18-
Set-NSHostname -Hostname ns01 -Force -Session $Session
19-
```

0 commit comments

Comments
 (0)