2.2. 설정 항목
각 설정은 세 가지 방법으로 넣을 수 있습니다 — web.xml(또는 addInitParameter), 환경변수, JVM 시스템 프로퍼티. 어느 방법으로 넣든 결과는 같습니다.
아래 "항목과 기본값" 은 web.xml 기준 이름으로 정리했습니다. 환경변수와 시스템 프로퍼티로 넣을 때 쓰는 이름은 그 아래 "이름 대응표" 에 있습니다.
셋을 함께 쓰면 다음 순서로 이깁니다.
1. 환경변수 KSM_SESSION_TIMEOUT ← 가장 세다
2. 시스템 프로퍼티 ksm.session.timeout
3. web.xml <param-name>sessionTimeout
같은 이미지를 여러 환경(개발·검증·운영)에 배포할 때 유용합니다. 애플리케이션은 그대로 두고 환경변수만 바꿔 동작을 조정할 수 있습니다.
이름을 바꾸는 규칙은 낱말 경계에 기호를 넣는 것입니다 — sessionTimeout → KSM_SESSION_TIMEOUT(환경변수) → ksm.session.timeout(시스템 프로퍼티).
web.xml 의 값 자체에도 ${변수:기본값} 을 쓸 수 있습니다. 예를 들어 <param-value>${session.timeout:30}</param-value> 은 시스템 프로퍼티 session.timeout 이 있으면 그 값을, 없으면 30 을 씁니다.
항목과 기본값
기본값은 소스의 KhanSessionFilter.getSessionFilterConfig() 기준입니다. 넣지 않으면 이 값이 쓰입니다.
저장소 연결
| 설정 이름 | 설명 | 기본값 |
|---|---|---|
| configFile | 세션 저장소 접속 정보를 담은 파일 이름 (2단계에서 만든 파일) | 없음 — 반드시 넣어야 합니다. 없으면 기동 시 오류가 납니다 |
| infinispanCache | 세션 메타 정보를 담을 캐시 이름 | KHAN_SESSION |
| infinispanLoginCache | 세션 데이터를 담을 캐시 이름 | KHAN_SESSION_LOGIN |
| namespace | 저장소 키 앞에 붙는 이름. 한 저장소를 여러 시스템이 나눠 쓸 때 구분합니다 | KHAN |
쿠키
| 설정 이름 | 설명 | 기본값 |
|---|---|---|
| sessionId | 세션을 식별하는 쿠키 이름. WAS 의 JSESSIONID 는 그대로 두고 이 쿠키가 추가되며, 데이터그리드에서 세션을 찾을 때는 이 값을 씁니다 | __KSMSID__ |
| domain | 세션을 공유할 도메인. 하위 도메인만 다른 경우 공유할 수 있습니다 (예: login.openmaru.io 와 www.openmaru.io) | (없음) |
| path | 세션을 공유할 경로. 서로 다른 웹 애플리케이션끼리 공유하려면 / 로 설정합니다 | / |
| secure | 쿠키의 Secure 옵션. HTTPS 로만 쿠키를 보냅니다 | false |
| httpOnly | 쿠키의 HttpOnly 옵션. 자바스크립트에서 쿠키를 읽지 못하게 합니다 | false |
| sameSite | 쿠키의 SameSite 옵션 | (없음) |
세션 동작
| 설정 이름 | 설명 | 기본값 |
|---|---|---|
| sessionTimeout | 세션 타임아웃(분). 숫자가 아닌 값을 넣으면 기본값이 쓰이고 오류가 로그에 남습니다 | 10 |
| sessionSaveDelay | 세션을 저장소에 쓰기까지 미루는 시간(초). 0 이면 미루지 않습니다 | 0 |
| excludeRegExp | 세션을 만들지 않을 요청 경로(정규식). 이미지·CSS 같은 정적 파일에 세션이 생기지 않게 합니다 | (없음 — 넣지 않으면 모든 요청에 세션이 생깁니다) |
| enableImmediateSave | true 면 setAttribute() 를 호출할 때마다 즉시 저장소에 저장합니다 | false |
| enableImmediateRead | true 면 세션 값을 읽을 때마다 저장소에서 바로 읽습니다 | false |
| useLibraryMode | 라이브러리 모드로 동작합니다. 원격 데이터그리드 모드에서는 쓰지 않습니다 | false |
| useAuthenticator | WAS 인증 연동을 사용합니다 | false |
중복 로그인
| 설정 이름 | 설명 | 기본값 |
|---|---|---|
| allowDuplicateLogin | 중복 로그인 허용 여부. 기본이 false 이므로 중복 로그인 방지가 처음부터 켜져 있습니다. 허용하려면 true 로 넣습니다 | false |
| duplicateLoginPolicy | 중복 로그인 정책. none 은 아무 동작도 하지 않고, legacy 는 이전에 로그인한 사용자를 로그아웃시키며, custom 은 중복 로그인된 세션 목록으로 관리합니다. allowDuplicateLogin 이 true 면 이 값은 무시되고 legacy 로 고정됩니다 | legacy |
| invalidateDuplicateLogin | 중복 로그인을 찾았을 때 기존 세션을 자동으로 무효화할지 여부. false 면 세션을 유지하고 로그아웃 URL 로만 보냅니다 | false |
| duplicateLoginExclustionType | 중복 로그인 검사에서 제외할 사용자 유형. 여러 개면 쉼표로 구분합니다 | (없음) |
| logoutUrl | 중복 로그인을 찾았을 때 보낼 로그아웃 URL. 비워 두면 보내지 않습니다 | (빈 문자열) |
모니터링
| 설정 이름 | 설명 | 기본값 |
|---|---|---|
| enableStatistics | 세션 지표를 MBean 으로 노출합니다. 기본이 켜짐입니다. 끄려면 false 를 넣습니다 | true |
| enableMemoryStatistics | 세션 메모리 사용량을 함께 측정합니다. 자바 에이전트 설정이 필요합니다 | false |
이름 대응표
같은 설정을 환경변수나 JVM 시스템 프로퍼티로 넣을 때 쓰는 이름입니다.
| 설정 이름 (web.xml) | 환경변수 | JVM 시스템 프로퍼티 |
|---|---|---|
| configFile | KSM_CONFIG_FILE | ksm.config.file |
| namespace | KSM_NAMESPACE | ksm.namespace |
| infinispanCache | KSM_INFINISPAN_CACHE | ksm.infinispan.cache |
| infinispanLoginCache | KSM_INFINISPAN_LOGIN_CACHE | ksm.infinispan.login.cache |
| sessionId | KSM_SESSION_ID | ksm.session.id |
| domain | KSM_DOMAIN | ksm.domain |
| path | KSM_PATH | ksm.path |
| secure | KSM_SECURE | ksm.secure |
| httpOnly | KSM_HTTP_ONLY | ksm.http.only |
| sameSite | KSM_SAME_SITE | ksm.same.site |
| sessionTimeout | KSM_SESSION_TIMEOUT | ksm.session.timeout |
| sessionSaveDelay | KSM_SESSION_SAVE_DELAY | ksm.session.save.delay |
| excludeRegExp | KSM_EXCLUDE_REG_EXP | ksm.exclude.reg.exp |
| allowDuplicateLogin | KSM_ALLOW_DUPLICATE_LOGIN | ksm.allow.duplicate.login |
| duplicateLoginPolicy | KSM_DUPLICATE_LOGIN_POLICY | ksm.duplicate.login.policy |
| invalidateDuplicateLogin | KSM_INVALIDATE_DUPLICATE_LOGIN | ksm.invalidate.duplicate.login |
| duplicateLoginExclustionType | KSM_DUPLICATE_LOGIN_EXCLUSTION_TYPE | ksm.duplicate.login.exclustion.type |
| logoutUrl | KSM_LOGOUT_URL | ksm.logout.url |
| enableImmediateSave | KSM_ENABLE_IMMEDIATE_SAVE | ksm.enable.immediate.save |
| enableStatistics | KSM_ENABLE_STATISTICS | ksm.enable.statistics |
| enableMemoryStatistics | KSM_ENABLE_MEMORY_STATISTICS | ksm.enable.memory.statistics |
| enableImmediateRead | KSM_ENABLE_IMMEDIATE_READ | ksm.enable.immediate.read |
| useLibraryMode | KSM_USE_LIBRARY_MODE | ksm.use.library.mode |
| useAuthenticator | KSM_USE_AUTHENTICATOR | ksm.use.authenticator |
configFile 은 OPENMARU_CONFIG_FILE 환경변수로도 지정할 수 있습니다.