DSCResources/DSC_SmbShare/en-US/about_SmbShare.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
.NAME
    SmbShare
 
.DESCRIPTION
    The resource is used to manage SMB shares, and access permissions to
    SMB shares.
 
    ## Requirements
 
    ### Cluster Shares
 
    The property `ContinuouslyAvailable` can only be set to `$true` when
    the SMB share is a cluster share in a failover cluster. Also in the blog
    [SMB Transparent Failover ? making file shares continuously available](https://blogs.technet.microsoft.com/filecab/2016/03/25/smb-transparent-failover-making-file-shares-continuously-available-2)
    by [Claus Joergensen](https://github.com/clausjor) it is mentioned that
    SMB Transparent Failover does not support cluster disks with 8.3 name
    generation enabled.
 
    ### Access permissions
 
    It is not allowed to provide empty collections in the configuration for
    the access permissions parameters. The configuration below will cause an
    exception to be thrown.
 
    ```powershell
    SmbShare 'Integration_Test'
    {
        Name = 'TestShare'
        Path = 'C:\Temp'
        FullAccess = @()
        ChangeAccess = @()
        ReadAccess = @()
        NoAccess = @()
    }
    ```
 
    The access permission parameters must either be all removed to manage
    the access permission manually, or add at least one member to one of
    the access permission parameters. If all the access permission parameters
    are removed, then by design, the cmdlet New-SmbShare will add
    the *Everyone* group with read access permission to the SMB share.
    To prevent that, add a member to either access permission parameters.
 
.PARAMETER Name
    Key - String
    Specifies the name of the SMB share.
 
.PARAMETER Path
    Required - String
    Specifies the path of the SMB share.
 
.PARAMETER Description
    Write - String
    Specifies the description of the SMB share.
 
.PARAMETER ChangeAccess
    Write - StringArray
    Specifies which accounts will be granted modify permission to access the SMB share.
 
.PARAMETER ConcurrentUserLimit
    Write - UInt32
    Specifies the maximum number of concurrently connected users that the new SMB share may accommodate. If this parameter is set to zero (0), then the number of users is unlimited. The default value is zero (0).
 
.PARAMETER EncryptData
    Write - Boolean
    Indicates that the SMB share is encrypted.
 
.PARAMETER FolderEnumerationMode
    Write - String
    Allowed values: AccessBased, Unrestricted
    Specifies which files and folders in the new SMB share are visible to users.
 
.PARAMETER CachingMode
    Write - String
    Allowed values: None, Manual, Programs, Documents, BranchCache
    Specifies the caching mode of the offline files for the SMB share.
 
.PARAMETER ContinuouslyAvailable
    Write - Boolean
    Specifies whether the SMB share should be continuously available.
 
.PARAMETER FullAccess
    Write - StringArray
    Specifies which accounts are granted full permission to access the SMB share.
 
.PARAMETER NoAccess
    Write - StringArray
    Specifies which accounts are denied access to the SMB share.
 
.PARAMETER ReadAccess
    Write - StringArray
    Specifies which accounts is granted read permission to access the SMB share.
 
.PARAMETER Ensure
    Write - String
    Allowed values: Present, Absent
    Specifies if the SMB share should be added or removed.
 
.PARAMETER Force
    Write - Boolean
    Specifies if the SMB share is allowed to be dropped and recreated (required when the path changes).
 
.PARAMETER ScopeName
    Write - String
    Specifies the scope in which the share should be created.
 
.PARAMETER ShareState
    Read - String
    Specifies the state of the SMB share.
 
.PARAMETER ShareType
    Read - String
    Specifies the type of the SMB share.
 
.PARAMETER ShadowCopy
    Read - Boolean
    Specifies if this SMB share is a ShadowCopy.
 
.PARAMETER Special
    Read - Boolean
    Specifies if this SMB share is a special share. E.g. an admin share, default shares, or IPC$ share.
 
.EXAMPLE 1
 
This example creates an SMB share named 'Temp' for the path 'C:\Temp',
using the default values of the cmdlet `New-SmbShare`.
 
.NOTES
To know the default values, see the documentation for the cmdlet
`New-SmbShare`.
 
Configuration SmbShare_CreateShare_Config
{
    Import-DscResource -ModuleName ComputerManagementDsc
 
    Node localhost
    {
        SmbShare 'TempShare'
        {
            Name = 'Temp'
            Path = 'C:\Temp'
        }
    }
}
 
.EXAMPLE 2
 
This example creates an SMB share named 'Temp' for the path 'C:\Temp',
using specific values for each supported property.
 
.NOTES
Any other property not yet s?pported will use the default values of the
cmdlet `New-SmbShare`.To know the default values, see the documentation
for the cmdlet `New-SmbShare`.
 
Configuration SmbShare_CreateShareAllProperties_Config
{
    Import-DscResource -ModuleName ComputerManagementDsc
 
    Node localhost
    {
        SmbShare 'TempShare'
        {
            Name = 'Temp'
            Path = 'C:\Temp'
            Description = 'Some description'
            ConcurrentUserLimit = 20
            EncryptData = $false
            FolderEnumerationMode = 'AccessBased'
            CachingMode = 'Manual'
            ContinuouslyAvailable = $false
            FullAccess = @()
            ChangeAccess = @('AdminUser1')
            ReadAccess = @('Everyone')
            NoAccess = @('DeniedUser1')
        }
    }
}
 
.EXAMPLE 3
 
This example removes a SMB share named 'Temp'.
 
.NOTES
Path must be specified because it is a mandatory parameter,
but it can be set to any value.
 
Configuration SmbShare_RemoveShare_Config
{
    Import-DscResource -ModuleName ComputerManagementDsc
 
    Node localhost
    {
        SmbShare 'TempShare'
        {
            Ensure = 'Absent'
            Name = 'Temp'
            Path = 'NotUsed'
        }
    }
}
 
.EXAMPLE 4
 
This example creates an SMB share named 'Share' for the path 'C:\Share1',
using the default values of the cmdlet `New-SmbShare`. If the share
already exists, it will drop the share and recreate it on the new path
because Force is set to true.
 
.NOTES
To know the default values, see the documentation for the cmdlet
`New-SmbShare`.
 
Configuration SmbShare_RecreateShare_Config
{
    Import-DscResource -ModuleName ComputerManagementDsc
 
    Node localhost
    {
        SmbShare 'RecreateShare'
        {
            Name = 'Share'
            Path = 'C:\Share1'
            Force = $true
        }
    }
}