Salt Documentation

2362 Pages·2015·6.61 MB·English

Salt Documentation
Release 2015.8.0
SaltStack, Inc.
September17,2015

Contents
1 IntroductiontoSalt 1
1.1 The30secondsummary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Simplicity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Parallelexecution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.4 Buildingonproventechnology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.5 Pythonclientinterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.6 Fast,flexible,scalable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.7 Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.8 SaltCommunity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.9 MailingList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.10 IRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.11 FollowonGitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.12 Blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.13 ExampleSaltStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.14 Followonohloh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.15 Othercommunitylinks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.16 HacktheSource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Installation 5
2.1 QuickInstall. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Platform-specificInstallationInstructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4 OptionalDependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5 UpgradingSalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3 Tutorials 27
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.3 States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.4 AdvancedTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5 SaltVirt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
3.6 LXC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
3.7 UsingSaltatscale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4 TargetingMinions 137
4.1 Matchingtheminion id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
4.2 Grains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.3 Subnet/IPAddressMatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
i
4.4 Compoundmatchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4.5 Nodegroups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.6 BatchSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.7 SECORange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5 StoringStaticDatainthePillar 147
5.1 DeclaringtheMasterPillar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.2 Pillarnamespaceflattened . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
5.3 PillarNamespaceMerges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.4 IncludingOtherPillars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.5 ViewingMinionPillar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.6 Pillar``get''Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.7 RefreshingPillarData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.8 TargetingwithPillar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.9 SetPillarDataattheCommandLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.10 MasterConfigInPillar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.11 MinionConfiginPillar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.12 MasterProvidedPillarError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6 ReactorSystem 153
6.1 EventSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.2 MappingEventstoReactorSLSFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.3 Fireanevent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.4 Knowingwhateventisbeingfired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.5 DebuggingtheReactor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.6 UnderstandingtheStructureofReactorFormulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.7 ACompleteExample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.8 SyncingCustomTypesonMinionStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7 TheSaltMine 161
7.1 MineFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.2 MineInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.3 MineinSalt-SSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8 ExternalAuthenticationSystem 165
8.1 AccessControlSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
8.2 Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.3 OpenLDAPandsimilarsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
8.4 ActiveDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
9 AccessControlSystem 169
10 JobManagement 171
10.1 TheMinionprocSystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
10.2 FunctionsinthesaltutilModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
10.3 ThejobsRunner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
10.4 SchedulingJobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
10.5 States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
10.6 Highstates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
10.7 Runners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
10.8 SchedulerWithReturner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
11 ManagingtheJobCache 179
11.1 DefaultJobCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
ii
11.2 AdditionalJobCacheOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
12 StoringJobResultsinanExternalSystem 181
12.1 ExternalJobCache-Minion-SideReturner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.2 MasterJobCache-Master-SideReturner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
12.3 ConfigureanExternalorMasterJobCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
13 StoringDatainOtherDatabases 185
13.1 SDBConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
13.2 SDBURIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
13.3 WritingSDBModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
14 SaltEventSystem 187
14.1 Eventtypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
14.2 ListeningforEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
14.3 FiringEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
14.4 FiringEventsfromPython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
15 Beacons 195
15.1 ConfiguringBeacons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
15.2 BeaconExample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
15.3 WritingBeaconPlugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
16 RunningCustomMasterProcesses 199
16.1 ExampleConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
16.2 ExampleProcessClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
17 HighAvailabilityFeaturesinSalt 201
17.1 Multimaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
17.2 MultimasterwithFailover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
17.3 Syndic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
17.4 SyndicwithMultimaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
18 SaltSyndic 203
18.1 ConfiguringtheSyndic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
18.2 ConfiguringtheSyndicwithMultimaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
18.3 RunningtheSyndic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
18.4 Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
18.5 Syndicwait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
18.6 Syndicconfigoptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
19 SaltProxyMinion 207
19.1 Newin2015.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
19.2 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
19.3 The__proxyenabled__directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
20 SaltPackageManager 217
20.1 BuildingPackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
20.2 BuildingRepositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
20.3 ConfiguringRemoteRepositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
20.4 InstallingPackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
20.5 Pillars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
20.6 LoaderModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
20.7 RemovingPackages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
20.8 TechnicalInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
iii
20.9 SPM-SpecificLoaderModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
20.10 SPMConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
20.11 TypesofPackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
21 SaltTransport 227
21.1 PubChannel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
21.2 ReqChannel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
22 WindowsSoftwareRepository 231
22.1 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
22.2 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
22.3 GenerateRepoCacheFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
22.4 InstallWindowsSoftware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
22.5 UninstallWindowsSoftware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
22.6 ManagingWindowsSoftwareonaStandaloneWindowsMinion . . . . . . . . . . . . . . . . . . . . 235
22.7 MinionConfigOptionsforReleasesOlderThan2015.8.0 . . . . . . . . . . . . . . . . . . . . . . . . . 235
22.8 MinionConfigOptionsforReleases2015.8.0andNewer . . . . . . . . . . . . . . . . . . . . . . . . . 235
22.9 MaintainingWindowsRepoDefinitionsinGitRepositories . . . . . . . . . . . . . . . . . . . . . . . 235
22.10 ChangesinVersion2015.8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
22.11 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
23 Windows-specificBehaviour 239
23.1 Groupparameterforfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
23.2 Dealingwithcase-insensitivebutcase-preservingnames . . . . . . . . . . . . . . . . . . . . . . . . . 239
23.3 Dealingwithvarioususernameforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
23.4 SpecifyingtheNonegroup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
23.5 Symboliclinkloops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
23.6 Modifyingsecurityproperties(ACLs)onfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
24 SaltCloud 241
24.1 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
24.2 UsingSaltCloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
24.3 CoreConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
24.4 WindowsConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
24.5 CloudProviderSpecifics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
24.6 MiscellaneousOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
24.7 TroubleshootingSteps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
24.8 ExtendingSaltCloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
24.9 UsingSaltCloudfromSalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
24.10 FeatureComparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
24.11 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
25 netapimodules 373
25.1 Writingnetapimodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
25.2 Introductiontonetapimodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
25.3 Clientinterfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
26 SaltVirt 377
26.1 SaltVirtTutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
26.2 TheSaltVirtRunner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
26.3 BasedonLiveStateData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
26.4 DeployfromNetworkorDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
27 UnderstandingYAML 381
27.1 RuleOne: Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
iv
27.2 RuleTwo: Colons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
27.3 RuleThree: Dashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
27.4 LearningMore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
28 MasterTopsSystem 383
29 SaltSSH 385
29.1 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
29.2 SaltSSHRoster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
29.3 CallingSaltSSH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
29.4 StatesViaSaltSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
29.5 TargetingwithSaltSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
29.6 ConfiguringSaltSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
29.7 RunningSaltSSHasnon-rootuser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
29.8 DefineCLIOptionswithSaltfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
30 SaltRosters 389
30.1 HowRostersWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
31 Reference 391
31.1 Fulllistofbuiltinauthmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
31.2 CommandLineReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
31.3 ClientACLsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
31.4 PythonclientAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
31.5 FulllistofSaltCloudmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
31.6 Configurationfileexamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
31.7 ConfiguringSalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
31.8 ConfiguringtheSaltMaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
31.9 ConfiguringtheSaltMinion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
31.10 RunningtheSaltMaster/MinionasanUnprivilegedUser. . . . . . . . . . . . . . . . . . . . . . . . . 579
31.11 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
31.12 ExternalLoggingHandlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
31.13 SaltFileServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
31.14 Fulllistofbuiltinfileservermodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
31.15 Saltcodeandinternals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
31.16 Fulllistofbuiltinexecutionmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
31.17 Fulllistofnetapimodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321
31.18 Fulllistofbuiltinoutputmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347
31.19 PeerCommunication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
31.20 Pillars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
31.21 Fulllistofbuiltinpillarmodules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
31.22 Renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
31.23 Returners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
31.24 Fulllistofbuiltinrostermodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
31.25 SaltRunners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
31.26 StateEnforcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469
31.27 Fulllistofbuiltinstatemodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1516
31.28 ExecutionModules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1774
31.29 MasterTops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
31.30 Fulllistofbuiltinmastertopsmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
31.31 Fulllistofbuiltinwheelmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
31.32 Fulllistofbuiltinbeaconmodules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
31.33 Fulllistofbuiltinenginemodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
31.34 Fulllistofbuiltinsdbmodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792
31.35 Fulllistofbuiltinserializers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
v
32 SaltBestPractices 1797
32.1 Generalrules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
32.2 StructuringStatesandFormulas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
32.3 StructuringPillarFiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
32.4 VariableFlexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
32.5 ModularityWithinStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
32.6 StoringSecureData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803
33 Troubleshooting 1805
33.1 TroubleshootingtheSaltMaster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805
33.2 TroubleshootingtheSaltMinion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
33.3 RunningintheForeground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
33.4 WhatPortsdotheMasterandMinionNeedOpen? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811
33.5 Usingsalt-call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811
33.6 Toomanyopenfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811
33.7 SaltMasterStopsResponding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
33.8 SaltandSELinux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
33.9 RedHatEnterpriseLinux5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
33.10 CommonYAMLGotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
33.11 LivePythonDebugOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
33.12 Salt0.16.xminionscannotcommunicatewitha0.17.xmaster . . . . . . . . . . . . . . . . . . . . . . 1818
33.13 DebuggingtheMasterandMinion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
34 DevelopingSalt 1819
34.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
34.2 SaltClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
34.3 SaltMaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
34.4 SaltMinion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
34.5 ANoteonClearFuncsvs. AESFuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822
34.6 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1823
34.7 DeprecatingCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1827
34.8 DunderDictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828
34.9 ExternalPillars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1830
34.10 InstallingSaltfordevelopment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
34.11 GitHubLabelsandMilestones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
34.12 LoggingInternals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841
34.13 ModularSystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841
34.14 PackageProviders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843
34.15 ReportingBugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1847
34.16 CommunityProjectsThatUseSalt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
34.17 SaltTopology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
34.18 TranslatingDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1849
34.19 RunningTheTests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1850
34.20 AutomatedTestRuns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852
34.21 WritingTests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852
34.22 raet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1865
34.23 SaltStackGitPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
34.24 SaltConventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869
35 Releasenotes 1903
35.1 LatestStableRelease . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
35.2 PreviousReleases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
36 SaltBasedProjects 2135
36.1 SaltSandbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
vi
37 Securitydisclosurepolicy 2137
37.1 Securityresponseprocedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
37.2 Receivingsecurityannouncements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
38 FrequentlyAskedQuestions 2139
38.1 IsSaltopen-core? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139
38.2 IthinkIfoundabug! WhatshouldIdo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139
38.3 WhatportsshouldIopenonmyfirewall? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2140
38.4 I'mseeingweirdbehavior(includingbutnotlimitedtopackagesnotinstallingtheirusersproperly) 2140
38.5 MyscriptrunseverytimeIrunastate.highstate. Why? . . . . . . . . . . . . . . . . . . . . . . . . . . 2140
38.6 When I run test.ping, why don't the Minions that aren't responding return anything? Returning
Falsewouldbehelpful. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2140
38.7 HowdoesSaltdeterminetheMinion'sid? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2141
38.8 I'mtryingtomanagepackages/servicesbutIgetanerrorsayingthatthestateisnotavailable. Why?2141
38.9 I'musinggitfsandmycustommodules/states/etcarenotsyncing. Why?. . . . . . . . . . . . . . . . 2141
38.10 Whyaren'tmycustommodules/states/etc. availableonmyMinions? . . . . . . . . . . . . . . . . . . 2141
38.11 ModuleXisn'tavailable,eventhoughtheshellcommanditusesisinstalled. Why? . . . . . . . . . . 2141
38.12 CanIrundifferentversionsofSaltonmyMasterandMinion? . . . . . . . . . . . . . . . . . . . . . 2142
38.13 DoesSaltsupportbackingupmanagedfiles? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2142
38.14 WhatisthebestwaytorestartaSaltdaemonusingSalt?. . . . . . . . . . . . . . . . . . . . . . . . . 2142
38.15 SaltingtheSaltMaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143
39 Glossary 2145
SaltModuleIndex 2149
Index 2157
vii
viii